@diottodev/runic 1.0.0 → 1.1.0

package/product/experiment-designer/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: experiment-designer
+description: Use when planning product experiments, writing testable hypotheses, estimating sample size, prioritizing tests, or interpreting A/B outcomes with practical statistical rigor.
+---
+
+# Experiment Designer
+
+Design, prioritize, and evaluate product experiments with clear hypotheses and defensible decisions.
+
+## When To Use
+
+Use this skill for:
+- A/B and multivariate experiment planning
+- Hypothesis writing and success criteria definition
+- Sample size and minimum detectable effect planning
+- Experiment prioritization with ICE scoring
+- Reading statistical output for product decisions
+
+## Core Workflow
+
+1. Write hypothesis in If/Then/Because format
+- If we change `[intervention]`
+- Then `[metric]` will change by `[expected direction/magnitude]`
+- Because `[behavioral mechanism]`
+
+2. Define metrics before running test
+- Primary metric: single decision metric
+- Guardrail metrics: quality/risk protection
+- Secondary metrics: diagnostics only
+
+3. Estimate sample size
+- Baseline conversion or baseline mean
+- Minimum detectable effect (MDE)
+- Significance level (alpha) and power
+
+Use:
+```bash
+python3 scripts/sample_size_calculator.py --baseline-rate 0.12 --mde 0.02 --mde-type absolute
+```
+
+4. Prioritize experiments with ICE
+- Impact: potential upside
+- Confidence: evidence quality
+- Ease: cost/speed/complexity
+
+ICE Score = (Impact * Confidence * Ease) / 10
+
+5. Launch with stopping rules
+- Decide fixed sample size or fixed duration in advance
+- Avoid repeated peeking without proper method
+- Monitor guardrails continuously
+
+6. Interpret results
+- Statistical significance is not business significance
+- Compare point estimate + confidence interval to decision threshold
+- Investigate novelty effects and segment heterogeneity
+
+## Hypothesis Quality Checklist
+
+- [ ] Contains explicit intervention and audience
+- [ ] Specifies measurable metric change
+- [ ] States plausible causal reason
+- [ ] Includes expected minimum effect
+- [ ] Defines failure condition
+
+## Common Experiment Pitfalls
+
+- Underpowered tests leading to false negatives
+- Running too many simultaneous changes without isolation
+- Changing targeting or implementation mid-test
+- Stopping early on random spikes
+- Ignoring sample ratio mismatch and instrumentation drift
+- Declaring success from p-value without effect-size context
+
+## Statistical Interpretation Guardrails
+
+- p-value < alpha indicates evidence against null, not guaranteed truth.
+- Confidence interval crossing zero/no-effect means uncertain directional claim.
+- Wide intervals imply low precision even when significant.
+- Use practical significance thresholds tied to business impact.
+
+See:
+- `references/experiment-playbook.md`
+- `references/statistics-reference.md`
+
+## Tooling
+
+### `scripts/sample_size_calculator.py`
+
+Computes required sample size (per variant and total) from:
+- baseline rate
+- MDE (absolute or relative)
+- significance level (alpha)
+- statistical power
+
+Example:
+```bash
+python3 scripts/sample_size_calculator.py \
+  --baseline-rate 0.10 \
+  --mde 0.015 \
+  --mde-type absolute \
+  --alpha 0.05 \
+  --power 0.8
+```

package/product/landing-page-generator/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: "landing-page-generator"
+description: "Generates high-converting landing pages as complete Next.js/React (TSX) components with Tailwind CSS. Creates hero sections, feature grids, pricing tables, FAQ accordions, testimonial blocks, and CTA sections using proven copy frameworks (PAS, AIDA, BAB). Outputs SEO meta tags, structured data, and performance-optimised code targeting Core Web Vitals (LCP < 1s, CLS < 0.1). Use when the user asks to create a landing page, marketing page, homepage, single-page site, lead capture page, campaign page, promo page, or conversion-optimised web page — or when they want to A/B test landing page variants or replace a static page with one designed to convert."
+---
+
+# Landing Page Generator
+
+Generate high-converting landing pages from a product description. Output complete Next.js/React components with multiple section variants, proven copy frameworks, SEO optimization, and performance-first patterns. Not lorem ipsum — actual copy that converts.
+
+**Target:** LCP < 1s · CLS < 0.1 · FID < 100ms  
+**Output:** TSX components + Tailwind styles + SEO meta + copy variants
+
+---
+
+## Core Capabilities
+
+- 5 hero section variants (centered, split, gradient, video-bg, minimal)
+- Feature sections (grid, alternating, cards with icons)
+- Pricing tables (2–4 tiers with feature lists and toggle)
+- FAQ accordion with schema markup
+- Testimonials (grid, carousel, single-quote)
+- CTA sections (banner, full-page, inline)
+- Footer (simple, mega, minimal)
+- 4 design styles with Tailwind class sets
+
+---
+
+## Generation Workflow
+
+Follow these steps in order for every landing page request:
+
+1. **Gather inputs** — collect product name, tagline, audience, pain point, key benefit, pricing tiers, design style, and copy framework using the trigger format below. Ask only for missing fields.
+2. **Analyze brand voice** (recommended) — if the user has existing brand content (website copy, blog posts, marketing materials), run it through `marketing-skill/content-production/scripts/brand_voice_analyzer.py` to get a voice profile (formality, tone, perspective). Use the profile to inform design style and copy framework selection:
+   - formal + professional → **enterprise** style, **AIDA** framework
+   - casual + friendly → **bold-startup** style, **BAB** framework
+   - professional + authoritative → **dark-saas** style, **PAS** framework
+   - casual + conversational → **clean-minimal** style, **BAB** framework
+3. **Select design style** — map the user's choice (or infer from brand voice analysis) to one of the four Tailwind class sets in the Design Style Reference.
+4. **Apply copy framework** — write all headline and body copy using the chosen framework (PAS / AIDA / BAB) before generating components. Match the voice profile's formality and tone throughout.
+5. **Generate sections in order** — Hero → Features → Pricing → FAQ → Testimonials → CTA → Footer. Skip sections not relevant to the product.
+6. **Validate against SEO checklist** — run through every item in the SEO Checklist before outputting final code. Fix any gaps inline.
+7. **Output final components** — deliver complete, copy-paste-ready TSX files with all Tailwind classes, SEO meta, and structured data included.
+
+---
+
+## Triggering This Skill
+
+```
+Product: [name]
+Tagline: [one sentence value prop]
+Target audience: [who they are]
+Key pain point: [what problem you solve]
+Key benefit: [primary outcome]
+Pricing tiers: [free/pro/enterprise or describe]
+Design style: dark-saas | clean-minimal | bold-startup | enterprise
+Copy framework: PAS | AIDA | BAB
+```
+
+---
+
+## Design Style Reference
+
+| Style | Background | Accent | Cards | CTA Button |
+|---|---|---|---|---|
+| **Dark SaaS** | `bg-gray-950 text-white` | `violet-500/400` | `bg-gray-900 border border-gray-800` | `bg-violet-600 hover:bg-violet-500` |
+| **Clean Minimal** | `bg-white text-gray-900` | `blue-600` | `bg-gray-50 border border-gray-200 rounded-2xl` | `bg-blue-600 hover:bg-blue-700` |
+| **Bold Startup** | `bg-white text-gray-900` | `orange-500` | `shadow-xl rounded-3xl` | `bg-orange-500 hover:bg-orange-600 text-white` |
+| **Enterprise** | `bg-slate-50 text-slate-900` | `slate-700` | `bg-white border border-slate-200 shadow-sm` | `bg-slate-900 hover:bg-slate-800 text-white` |
+
+> **Bold Startup** headings: add `font-black tracking-tight` to all `<h1>`/`<h2>` elements.
+
+---
+
+## Copy Frameworks
+
+**PAS (Problem → Agitate → Solution)**
+- H1: Painful state they're in
+- Sub: What happens if they don't fix it
+- CTA: What you offer
+- *Example — H1:* "Your team wastes 3 hours a day on manual reporting" / *Sub:* "Every hour spent on spreadsheets is an hour not closing deals. Your competitors are already automated." / *CTA:* "Automate your reports in 10 minutes →"
+
+**AIDA (Attention → Interest → Desire → Action)**
+- H1: Bold attention-grabbing statement → Sub: Interesting fact or benefit → Features: Desire-building proof points → CTA: Clear action
+
+**BAB (Before → After → Bridge)**
+- H1: "[Before state] → [After state]" → Sub: "Here's how [product] bridges the gap" → Features: How it works (the bridge)
+
+---
+
+## Representative Component: Hero (Centered Gradient — Dark SaaS)
+
+Use this as the structural template for all hero variants. Swap layout classes, gradient direction, and image placement for split, video-bg, and minimal variants.
+
+```tsx
+export function HeroCentered() {
+  return (
+    <section className="relative flex min-h-screen flex-col items-center justify-center overflow-hidden bg-gray-950 px-4 text-center">
+      <div className="absolute inset-0 bg-gradient-to-b from-violet-900/20 to-transparent" />
+      <div className="pointer-events-none absolute -top-40 left-1/2 h-[600px] w-[600px] -translate-x-1/2 rounded-full bg-violet-600/20 blur-3xl" />
+      <div className="relative z-10 max-w-4xl">
+        <div className="mb-6 inline-flex items-center gap-2 rounded-full border border-violet-500/30 bg-violet-500/10 px-4 py-1.5 text-sm text-violet-300">
+          <span className="h-1.5 w-1.5 rounded-full bg-violet-400" />
+          Now in public beta
+        </div>
+        <h1 className="mb-6 text-5xl font-bold tracking-tight text-white md:text-7xl">
+          Ship faster.<br />
+          <span className="bg-gradient-to-r from-violet-400 to-pink-400 bg-clip-text text-transparent">
+            Break less.
+          </span>
+        </h1>
+        <p className="mx-auto mb-10 max-w-2xl text-xl text-gray-400">
+          The deployment platform that catches errors before your users do.
+          Zero config. Instant rollbacks. Real-time monitoring.
+        </p>
+        <div className="flex flex-col items-center gap-4 sm:flex-row sm:justify-center">
+          <Button size="lg" className="bg-violet-600 text-white hover:bg-violet-500 px-8">
+            Start free trial
+          </Button>
+          <Button size="lg" variant="outline" className="border-gray-700 text-gray-300">
+            See how it works →
+          </Button>
+        </div>
+        <p className="mt-4 text-sm text-gray-500">No credit card required · 14-day free trial</p>
+      </div>
+    </section>
+  )
+}
+```
+
+---
+
+## Other Section Patterns
+
+### Feature Section (Alternating)
+
+Map over a `features` array with `{ title, description, image, badge }`. Toggle layout direction with `i % 2 === 1 ? "lg:flex-row-reverse" : ""`. Use `<Image>` with explicit `width`/`height` and `rounded-2xl shadow-xl`. Wrap in `<section className="py-24">` with `max-w-6xl` container.
+
+### Pricing Table
+
+Map over a `plans` array with `{ name, price, description, features[], cta, highlighted }`. Highlighted plan gets `border-2 border-violet-500 bg-violet-950/50 ring-4 ring-violet-500/20`; others get `border border-gray-800 bg-gray-900`. Render `null` price as "Custom". Use `<Check>` icon per feature row. Layout: `grid gap-8 lg:grid-cols-3`.
+
+### FAQ with Schema Markup
+
+Inject `FAQPage` JSON-LD via `<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }} />` inside the section. Map FAQs with `{ q, a }` into shadcn `<Accordion>` with `type="single" collapsible`. Container: `max-w-3xl`.
+
+### Testimonials, CTA, Footer
+
+- **Testimonials:** Grid (`grid-cols-1 md:grid-cols-3`) or single-quote hero block with avatar, name, role, and quote text.
+- **CTA Banner:** Full-width section with headline, subhead, and two buttons (primary + ghost). Add trust signals (money-back guarantee, logo strip) immediately below.
+- **Footer:** Logo + nav columns + social links + legal. Use `border-t border-gray-800` separator.
+
+---
+
+## SEO Checklist
+
+- [ ] `<title>` tag: primary keyword + brand (50–60 chars)
+- [ ] Meta description: benefit + CTA (150–160 chars)
+- [ ] OG image: 1200×630px with product name and tagline
+- [ ] H1: one per page, includes primary keyword
+- [ ] Structured data: FAQPage, Product, or Organization schema
+- [ ] Canonical URL set
+- [ ] Image alt text on all `<Image>` components
+- [ ] robots.txt and sitemap.xml configured
+- [ ] Core Web Vitals: LCP < 1s, CLS < 0.1
+- [ ] Mobile viewport meta tag present
+- [ ] Internal linking to pricing and docs
+
+> **Validation step:** Before outputting final code, verify every checklist item above is satisfied. Fix any gaps inline — do not skip items.
+
+---
+
+## Performance Targets
+
+| Metric | Target | Technique |
+|---|---|---|
+| LCP | < 1s | Preload hero image, use `priority` on Next/Image |
+| CLS | < 0.1 | Set explicit width/height on all images |
+| FID/INP | < 100ms | Defer non-critical JS, use `loading="lazy"` |
+| TTFB | < 200ms | Use ISR or static generation for landing pages |
+| Bundle | < 100KB JS | Audit with `@next/bundle-analyzer` |
+
+---
+
+## Common Pitfalls
+
+- Hero image not preloaded — add `priority` prop to first `<Image>`
+- Missing mobile breakpoints — always design mobile-first with `sm:` prefixes
+- CTA copy too vague — "Get started" beats "Learn more"; "Start free trial" beats "Sign up"
+- Pricing page missing trust signals — add money-back guarantee and testimonials near CTA
+- No above-the-fold CTA on mobile — ensure button is visible without scrolling on 375px viewport
+
+---
+
+## Related Skills
+
+- **Brand Voice Analyzer** (`marketing-skill/content-production/scripts/brand_voice_analyzer.py`) — Run before generation to establish voice profile and ensure copy consistency
+- **UI Design System** (`product-team/ui-design-system/`) — Generate design tokens from brand color before building the page
+- **Competitive Teardown** (`product-team/competitive-teardown/`) — Competitive positioning informs landing page messaging and differentiation

package/product/product-analytics/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: product-analytics
+description: Use when defining product KPIs, building metric dashboards, running cohort or retention analysis, or interpreting feature adoption trends across product stages.
+---
+
+# Product Analytics
+
+Define, track, and interpret product metrics across discovery, growth, and mature product stages.
+
+## When To Use
+
+Use this skill for:
+- Metric framework selection (AARRR, North Star, HEART)
+- KPI definition by product stage (pre-PMF, growth, mature)
+- Dashboard design and metric hierarchy
+- Cohort and retention analysis
+- Feature adoption and funnel interpretation
+
+## Workflow
+
+1. Select metric framework
+- AARRR for growth loops and funnel visibility
+- North Star for cross-functional strategic alignment
+- HEART for UX quality and user experience measurement
+
+2. Define stage-appropriate KPIs
+- Pre-PMF: activation, early retention, qualitative success
+- Growth: acquisition efficiency, expansion, conversion velocity
+- Mature: retention depth, revenue quality, operational efficiency
+
+3. Design dashboard layers
+- Executive layer: 5-7 directional metrics
+- Product health layer: acquisition, activation, retention, engagement
+- Feature layer: adoption, depth, repeat usage, outcome correlation
+
+4. Run cohort + retention analysis
+- Segment by signup cohort or feature exposure cohort
+- Compare retention curves, not single-point snapshots
+- Identify inflection points around onboarding and first value moment
+
+5. Interpret and act
+- Connect metric movement to product changes and release timeline
+- Distinguish signal from noise using period-over-period context
+- Propose one clear product action per major metric risk/opportunity
+
+## KPI Guidance By Stage
+
+### Pre-PMF
+- Activation rate
+- Week-1 retention
+- Time-to-first-value
+- Problem-solution fit interview score
+
+### Growth
+- Funnel conversion by stage
+- Monthly retained users
+- Feature adoption among new cohorts
+- Expansion / upsell proxy metrics
+
+### Mature
+- Net revenue retention aligned product metrics
+- Power-user share and depth of use
+- Churn risk indicators by segment
+- Reliability and support-deflection product metrics
+
+## Dashboard Design Principles
+
+- Show trends, not isolated point estimates.
+- Keep one owner per KPI.
+- Pair each KPI with target, threshold, and decision rule.
+- Use cohort and segment filters by default.
+- Prefer comparable time windows (weekly vs weekly, monthly vs monthly).
+
+See:
+- `references/metrics-frameworks.md`
+- `references/dashboard-templates.md`
+
+## Cohort Analysis Method
+
+1. Define cohort anchor event (signup, activation, first purchase).
+2. Define retained behavior (active day, key action, repeat session).
+3. Build retention matrix by cohort week/month and age period.
+4. Compare curve shape across cohorts.
+5. Flag early drop points and investigate journey friction.
+
+## Retention Curve Interpretation
+
+- Sharp early drop, low plateau: onboarding mismatch or weak initial value.
+- Moderate drop, stable plateau: healthy core audience with predictable churn.
+- Flattening at low level: product used occasionally, revisit value metric.
+- Improving newer cohorts: onboarding or positioning improvements are working.
+
+## Anti-Patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| **Vanity metrics** — tracking pageviews or total signups without activation context | Always pair acquisition metrics with activation rate and retention |
+| **Single-point retention** — reporting "30-day retention is 20%" | Compare retention curves across cohorts, not isolated snapshots |
+| **Dashboard overload** — 30+ metrics on one screen | Executive layer: 5-7 metrics. Feature layer: per-feature only |
+| **No decision rule** — tracking a KPI with no threshold or action plan | Every KPI needs: target, threshold, owner, and "if below X, then Y" |
+| **Averaging across segments** — reporting blended metrics that hide segment differences | Always segment by cohort, plan tier, channel, or geography |
+| **Ignoring seasonality** — comparing this week to last week without adjusting | Use period-over-period with same-period-last-year context |
+
+## Tooling
+
+### `scripts/metrics_calculator.py`
+
+CLI utility for retention, cohort, and funnel analysis from CSV data. Supports text and JSON output.
+
+```bash
+# Retention analysis
+python3 scripts/metrics_calculator.py retention events.csv
+python3 scripts/metrics_calculator.py retention events.csv --format json
+
+# Cohort matrix
+python3 scripts/metrics_calculator.py cohort events.csv --cohort-grain month
+python3 scripts/metrics_calculator.py cohort events.csv --cohort-grain week --format json
+
+# Funnel conversion
+python3 scripts/metrics_calculator.py funnel funnel.csv --stages visit,signup,activate,pay
+python3 scripts/metrics_calculator.py funnel funnel.csv --stages visit,signup,activate,pay --format json
+```
+
+**CSV format for retention/cohort:**
+```csv
+user_id,cohort_date,activity_date
+u001,2026-01-01,2026-01-01
+u001,2026-01-01,2026-01-03
+u002,2026-01-02,2026-01-02
+```
+
+**CSV format for funnel:**
+```csv
+user_id,stage
+u001,visit
+u001,signup
+u001,activate
+u002,visit
+u002,signup
+```
+
+## Cross-References
+
+- Related: `product-team/experiment-designer` — for A/B test planning after identifying metric opportunities
+- Related: `product-team/product-manager-toolkit` — for RICE prioritization of metric-driven features
+- Related: `product-team/product-discovery` — for assumption mapping when metrics reveal unknowns
+- Related: `finance/saas-metrics-coach` — for SaaS-specific metrics (ARR, MRR, churn, LTV)

package/product/product-discovery/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: product-discovery
+description: Use when validating product opportunities, mapping assumptions, planning discovery sprints, or testing problem-solution fit before committing delivery resources.
+---
+
+# Product Discovery
+
+Run structured discovery to identify high-value opportunities and de-risk product bets.
+
+## When To Use
+
+Use this skill for:
+- Opportunity Solution Tree facilitation
+- Assumption mapping and test planning
+- Problem validation interviews and evidence synthesis
+- Solution validation with prototypes/experiments
+- Discovery sprint planning and outputs
+
+## Core Discovery Workflow
+
+1. Define desired outcome
+- Set one measurable outcome to improve.
+- Establish baseline and target horizon.
+
+2. Build Opportunity Solution Tree (OST)
+- Outcome -> opportunities -> solution ideas -> experiments
+- Keep opportunities grounded in user evidence, not internal opinions.
+
+3. Map assumptions
+- Identify desirability, viability, feasibility, and usability assumptions.
+- Score assumptions by risk and certainty.
+
+Use:
+```bash
+python3 scripts/assumption_mapper.py assumptions.csv
+```
+
+4. Validate the problem
+- Conduct interviews and behavior analysis.
+- Confirm frequency, severity, and willingness to solve.
+- Reject weak opportunities early.
+
+5. Validate the solution
+- Prototype before building.
+- Run concept, usability, and value tests.
+- Measure behavior, not only stated preference.
+
+6. Plan discovery sprint
+- 1-2 week cycle with explicit hypotheses
+- Daily evidence reviews
+- End with decision: proceed, pivot, or stop
+
+## Opportunity Solution Tree (Teresa Torres)
+
+Structure:
+- Outcome: metric you want to move
+- Opportunities: unmet customer needs/pains
+- Solutions: candidate interventions
+- Experiments: fastest learning actions
+
+Quality checks:
+- At least 3 distinct opportunities before converging.
+- At least 2 experiments per top opportunity.
+- Tie every branch to evidence source.
+
+## Assumption Mapping
+
+Assumption categories:
+- Desirability: users want this
+- Viability: business value exists
+- Feasibility: team can build/operate it
+- Usability: users can successfully use it
+
+Prioritization rule:
+- High risk + low certainty assumptions are tested first.
+
+## Problem Validation Techniques
+
+- Problem interviews focused on current behavior
+- Journey friction mapping
+- Support ticket and sales-call synthesis
+- Behavioral analytics triangulation
+
+Evidence threshold examples:
+- Same pain repeated across multiple target users
+- Observable workaround behavior
+- Measurable cost of current pain
+
+## Solution Validation Techniques
+
+- Concept tests (value proposition comprehension)
+- Prototype usability tests (task success/time-to-complete)
+- Fake door or concierge tests (demand signal)
+- Limited beta cohorts (retention/activation signals)
+
+## Discovery Sprint Planning
+
+Suggested 10-day structure:
+- Day 1-2: Outcome + opportunity framing
+- Day 3-4: Assumption mapping + test design
+- Day 5-7: Problem and solution tests
+- Day 8-9: Evidence synthesis + decision options
+- Day 10: Stakeholder decision review
+
+## Tooling
+
+### `scripts/assumption_mapper.py`
+
+CLI utility that:
+- reads assumptions from CSV or inline input
+- scores risk/certainty priority
+- emits prioritized test plan with suggested test types
+
+See `references/discovery-frameworks.md` for framework details.