claude-code-arcane 1.0.0

package/skills/product-analytics/scripts/metrics_calculator.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Product metrics calculator: retention, cohort matrix, and funnel conversion."""
+
+import argparse
+import csv
+import datetime as dt
+import json
+import sys
+from collections import defaultdict
+
+
+def parse_date(value: str) -> dt.date:
+    return dt.date.fromisoformat(value.strip()[:10])
+
+
+def load_csv(path: str):
+    with open(path, "r", encoding="utf-8", newline="") as handle:
+        return list(csv.DictReader(handle))
+
+
+def retention(args: argparse.Namespace) -> int:
+    rows = load_csv(args.input)
+    cohorts = {}
+    activity = defaultdict(set)
+
+    for row in rows:
+        user = row[args.user_column].strip()
+        cohort_date = parse_date(row[args.cohort_column])
+        activity_date = parse_date(row[args.activity_column])
+        cohorts[user] = min(cohorts.get(user, cohort_date), cohort_date)
+        delta = (activity_date - cohorts[user]).days
+        if delta >= 0:
+            activity[delta].add(user)
+
+    base_users = len(cohorts)
+    if base_users == 0:
+        print("No users found.", file=sys.stderr)
+        return 1
+
+    results = []
+    for period in range(0, args.max_period + 1):
+        users = len(activity.get(period, set()))
+        rate = users / base_users
+        results.append({"period": period, "active_users": users, "retention_rate": round(rate, 4)})
+
+    if getattr(args, "format", "text") == "json":
+        print(json.dumps({"base_users": base_users, "periods": results}, indent=2))
+    else:
+        print("Retention by period")
+        print("period,active_users,retention_rate")
+        for r in results:
+            print(f"{r['period']},{r['active_users']},{r['retention_rate']:.4f}")
+    return 0
+
+
+def cohort(args: argparse.Namespace) -> int:
+    rows = load_csv(args.input)
+    cohorts = {}
+    activity = defaultdict(set)
+
+    for row in rows:
+        user = row[args.user_column].strip()
+        cohort_date = parse_date(row[args.cohort_column])
+        activity_date = parse_date(row[args.activity_column])
+
+        if args.cohort_grain == "month":
+            cohort_key = cohort_date.strftime("%Y-%m")
+        else:
+            cohort_key = f"{cohort_date.isocalendar().year}-W{cohort_date.isocalendar().week:02d}"
+
+        cohorts.setdefault(user, cohort_key)
+        age = (activity_date - cohort_date).days
+        if age >= 0:
+            activity[(cohort_key, age)].add(user)
+
+    cohort_sizes = defaultdict(int)
+    for cohort_key in cohorts.values():
+        cohort_sizes[cohort_key] += 1
+
+    cohort_keys = sorted(cohort_sizes.keys())
+    results = []
+    for cohort_key in cohort_keys:
+        size = cohort_sizes[cohort_key]
+        for age in range(0, args.max_period + 1):
+            active = len(activity.get((cohort_key, age), set()))
+            rate = (active / size) if size else 0
+            results.append({"cohort": cohort_key, "age_days": age, "active_users": active,
+                            "cohort_size": size, "retention_rate": round(rate, 4)})
+
+    if getattr(args, "format", "text") == "json":
+        print(json.dumps({"cohorts": dict(cohort_sizes), "rows": results}, indent=2))
+    else:
+        print("cohort,age_days,active_users,cohort_size,retention_rate")
+        for r in results:
+            print(f"{r['cohort']},{r['age_days']},{r['active_users']},{r['cohort_size']},{r['retention_rate']:.4f}")
+    return 0
+
+
+def funnel(args: argparse.Namespace) -> int:
+    rows = load_csv(args.input)
+    stages = [item.strip() for item in args.stages.split(",") if item.strip()]
+    if not stages:
+        print("No stages provided.")
+        return 1
+
+    stage_users = {stage: set() for stage in stages}
+    for row in rows:
+        user = row[args.user_column].strip()
+        stage = row[args.stage_column].strip()
+        if stage in stage_users:
+            stage_users[stage].add(user)
+
+    results = []
+    previous_count = None
+    first_count = None
+    for stage in stages:
+        count = len(stage_users[stage])
+        if first_count is None:
+            first_count = count
+        conv_prev = (count / previous_count) if previous_count else 1.0
+        conv_first = (count / first_count) if first_count else 0
+        results.append({"stage": stage, "users": count,
+                        "conversion_from_previous": round(conv_prev, 4),
+                        "conversion_from_first": round(conv_first, 4)})
+        previous_count = count
+
+    if getattr(args, "format", "text") == "json":
+        print(json.dumps({"stages": results}, indent=2))
+    else:
+        print("stage,users,conversion_from_previous,conversion_from_first")
+        for r in results:
+            print(f"{r['stage']},{r['users']},{r['conversion_from_previous']:.4f},{r['conversion_from_first']:.4f}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Calculate retention, cohort, and funnel metrics from CSV data."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    common = {
+        "help": "CSV input path",
+    }
+
+    fmt_help = "Output format (default: text)"
+
+    retention_parser = subparsers.add_parser("retention", help="Calculate retention by day.")
+    retention_parser.add_argument("input", **common)
+    retention_parser.add_argument("--user-column", default="user_id")
+    retention_parser.add_argument("--cohort-column", default="cohort_date")
+    retention_parser.add_argument("--activity-column", default="activity_date")
+    retention_parser.add_argument("--max-period", type=int, default=30)
+    retention_parser.add_argument("--format", choices=["text", "json"], default="text", help=fmt_help)
+    retention_parser.set_defaults(func=retention)
+
+    cohort_parser = subparsers.add_parser("cohort", help="Build cohort retention matrix rows.")
+    cohort_parser.add_argument("input", **common)
+    cohort_parser.add_argument("--user-column", default="user_id")
+    cohort_parser.add_argument("--cohort-column", default="cohort_date")
+    cohort_parser.add_argument("--activity-column", default="activity_date")
+    cohort_parser.add_argument("--cohort-grain", choices=["week", "month"], default="week")
+    cohort_parser.add_argument("--max-period", type=int, default=30)
+    cohort_parser.add_argument("--format", choices=["text", "json"], default="text", help=fmt_help)
+    cohort_parser.set_defaults(func=cohort)
+
+    funnel_parser = subparsers.add_parser("funnel", help="Calculate funnel conversion by stage.")
+    funnel_parser.add_argument("input", **common)
+    funnel_parser.add_argument("--user-column", default="user_id")
+    funnel_parser.add_argument("--stage-column", default="stage")
+    funnel_parser.add_argument("--stages", required=True)
+    funnel_parser.add_argument("--format", choices=["text", "json"], default="text", help=fmt_help)
+    funnel_parser.set_defaults(func=funnel)
+
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        return args.func(args)
+    except FileNotFoundError:
+        print(f"Error: file not found: {args.input}", file=sys.stderr)
+        return 1
+    except KeyError as e:
+        print(f"Error: column not found in CSV: {e}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/product-discovery/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: product-discovery
+description: "Run structured discovery to validate product opportunities, map assumptions, plan discovery sprints, and test problem-solution fit before committing delivery resources."
+argument-hint: ""
+category: "agile"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# 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.

package/skills/product-discovery/references/discovery-frameworks.md

@@ -0,0 +1,72 @@
+# Discovery Frameworks
+
+## Opportunity Solution Tree (OST)
+
+Purpose: continuously connect product outcomes to validated opportunities and tested solutions.
+
+Core structure:
+- Outcome (metric)
+- Opportunity nodes (needs/pains)
+- Solution ideas
+- Experiments
+
+OST practice tips:
+- Keep tree live; update after each interview or test.
+- Separate opportunity evidence from solution proposals.
+- Avoid single-branch trees that force one solution.
+
+## Jobs-to-be-Done (JTBD)
+
+Use JTBD to understand progress users seek.
+
+JTBD template:
+"When [situation], I want to [motivation], so I can [expected outcome]."
+
+JTBD interview focus:
+- Trigger moments
+- Current alternatives and workarounds
+- Purchase/adoption anxieties
+- Desired progress and success criteria
+
+## Kano Model
+
+Classify features by impact on satisfaction:
+- Must-be: expected baseline features
+- Performance: more is better
+- Delighters: unexpected value multipliers
+- Indifferent: low impact
+- Reverse: can reduce satisfaction for some users
+
+Use Kano when prioritizing solution concepts after problem validation.
+
+## Design Sprint Methodology
+
+Typical phases:
+1. Understand
+2. Sketch
+3. Decide
+4. Prototype
+5. Test
+
+Discovery usage:
+- Compress learning cycle into one week.
+- Best for high-ambiguity opportunities requiring cross-functional alignment.
+
+## Assumption Prioritization Matrix
+
+Map assumptions on two axes:
+- Risk if wrong (low -> high)
+- Certainty (low -> high)
+
+Priority order:
+1. High risk, low certainty (test first)
+2. High risk, high certainty (validate quickly)
+3. Low risk, low certainty (defer)
+4. Low risk, high certainty (document)
+
+## Discovery Evidence Rules
+
+- One source is not enough for major decisions.
+- Triangulate qualitative and quantitative signals.
+- Predefine decision criteria before test execution.
+- Archive evidence with date, segment, and method.

package/skills/product-discovery/scripts/assumption_mapper.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Prioritize product assumptions and suggest validation tests."""
+
+import argparse
+import csv
+from dataclasses import dataclass
+
+
+@dataclass
+class Assumption:
+    statement: str
+    category: str
+    risk: float
+    certainty: float
+
+    @property
+    def priority_score(self) -> float:
+        # High-risk, low-certainty assumptions should be tested first.
+        return self.risk * (1.0 - self.certainty)
+
+
+def parse_float(value: str, field: str) -> float:
+    number = float(value)
+    if number < 0 or number > 1:
+        raise ValueError(f"{field} must be in [0, 1]")
+    return number
+
+
+def suggest_test(category: str) -> str:
+    category = category.lower().strip()
+    if category == "desirability":
+        return "problem interviews or fake-door test"
+    if category == "viability":
+        return "pricing/willingness-to-pay test"
+    if category == "feasibility":
+        return "technical spike or architecture prototype"
+    if category == "usability":
+        return "moderated usability test"
+    return "smallest possible experiment with clear success criteria"
+
+
+def load_from_csv(path: str) -> list[Assumption]:
+    assumptions: list[Assumption] = []
+    with open(path, "r", encoding="utf-8", newline="") as handle:
+        reader = csv.DictReader(handle)
+        required = {"assumption", "category", "risk", "certainty"}
+        missing = required - set(reader.fieldnames or [])
+        if missing:
+            missing_str = ", ".join(sorted(missing))
+            raise ValueError(f"Missing required columns: {missing_str}")
+
+        for row in reader:
+            assumptions.append(
+                Assumption(
+                    statement=(row.get("assumption") or "").strip(),
+                    category=(row.get("category") or "").strip(),
+                    risk=parse_float(row.get("risk") or "0", "risk"),
+                    certainty=parse_float(row.get("certainty") or "0", "certainty"),
+                )
+            )
+    return assumptions
+
+
+def parse_inline(items: list[str]) -> list[Assumption]:
+    assumptions: list[Assumption] = []
+    for item in items:
+        # format: statement|category|risk|certainty
+        parts = [part.strip() for part in item.split("|")]
+        if len(parts) != 4:
+            raise ValueError("Inline assumption must be: statement|category|risk|certainty")
+        assumptions.append(
+            Assumption(
+                statement=parts[0],
+                category=parts[1],
+                risk=parse_float(parts[2], "risk"),
+                certainty=parse_float(parts[3], "certainty"),
+            )
+        )
+    return assumptions
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Prioritize assumptions and generate test plan.")
+    parser.add_argument("input", nargs="?", help="CSV file path")
+    parser.add_argument(
+        "--assumption",
+        action="append",
+        default=[],
+        help="Inline assumption: statement|category|risk|certainty",
+    )
+    parser.add_argument("--top", type=int, default=10, help="Maximum assumptions to print")
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    assumptions: list[Assumption] = []
+    if args.input:
+        assumptions.extend(load_from_csv(args.input))
+    if args.assumption:
+        assumptions.extend(parse_inline(args.assumption))
+
+    if not assumptions:
+        parser.error("Provide a CSV input file or at least one --assumption value.")
+
+    assumptions.sort(key=lambda item: item.priority_score, reverse=True)
+
+    print("prioritized_assumption_test_plan")
+    print("rank,priority_score,category,risk,certainty,test,assumption")
+    for rank, item in enumerate(assumptions[: args.top], start=1):
+        test = suggest_test(item.category)
+        print(
+            f"{rank},{item.priority_score:.4f},{item.category},{item.risk:.2f},"
+            f"{item.certainty:.2f},{test},{item.statement}"
+        )
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/product-manager-toolkit/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: product-manager-toolkit
+description: "Comprehensive PM toolkit with RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies."
+argument-hint: ""
+category: "agile"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Product Manager Toolkit
+
+Essential tools and frameworks for modern product management, from discovery to delivery.
+
+## Quick Start
+
+```bash
+# Create sample data file
+python scripts/rice_prioritizer.py sample
+
+# Run prioritization with team capacity
+python scripts/rice_prioritizer.py sample_features.csv --capacity 15
+
+# Analyze interview transcript
+python scripts/customer_interview_analyzer.py interview_transcript.txt
+```
+
+## Core Workflows
+
+### Feature Prioritization Process
+
+```
+Gather -> Score -> Analyze -> Plan -> Validate -> Execute
+```
+
+1. **Gather Feature Requests**: Customer feedback, sales requests, tech debt, strategic initiatives
+2. **Score with RICE**: `python scripts/rice_prioritizer.py features.csv --capacity 20`
+   See `references/frameworks.md` for RICE formula and scoring guidelines.
+3. **Analyze Portfolio**: Quick wins vs big bets distribution, effort concentration, strategic alignment gaps
+4. **Generate Roadmap**: Quarterly capacity allocation, dependency identification, stakeholder communication
+5. **Validate Results**:
+   - Compare top priorities against strategic goals
+   - Run sensitivity analysis (what if estimates are wrong by 2x?)
+   - Validate effort estimates with engineering
+6. **Execute and Iterate**: Share roadmap, track actual vs estimated effort, revisit quarterly
+
+### Customer Discovery Process
+
+```
+Plan -> Recruit -> Interview -> Analyze -> Synthesize -> Validate
+```
+
+1. **Plan Research**: Define research questions, identify target segments, create interview script
+2. **Recruit Participants**: 5-8 interviews per segment, mix of power users and churned users
+3. **Conduct Interviews**: Semi-structured format, focus on problems not solutions, record with permission
+4. **Analyze Insights**: `python scripts/customer_interview_analyzer.py transcript.txt`
+   Extracts: pain points, feature requests, JTBD patterns, sentiment, key themes, notable quotes
+5. **Synthesize Findings**: Group similar pain points, identify patterns (3+ mentions = pattern), map to opportunity areas
+6. **Validate Solutions**: Create solution hypotheses, test with low-fidelity prototypes, measure behavior
+
+### PRD Development Process
+
+```
+Scope -> Draft -> Review -> Refine -> Approve -> Track
+```
+
+Select template from `references/prd_templates.md`:
+
+| Template | Use Case | Timeline |
+|----------|----------|----------|
+| Standard PRD | Complex features, cross-team | 6-8 weeks |
+| One-Page PRD | Simple features, single team | 2-4 weeks |
+| Feature Brief | Exploration phase | 1 week |
+| Agile Epic | Sprint-based delivery | Ongoing |
+
+## Tools Reference
+
+### RICE Prioritizer
+
+RICE framework implementation with portfolio analysis, configurable weights, and multiple output formats.
+
+```bash
+python scripts/rice_prioritizer.py sample                          # Create sample data
+python scripts/rice_prioritizer.py features.csv                    # Default capacity (10)
+python scripts/rice_prioritizer.py features.csv --capacity 20      # Custom capacity
+python scripts/rice_prioritizer.py features.csv --output json      # JSON output
+python scripts/rice_prioritizer.py features.csv --output csv       # CSV output
+```
+
+> See references/input-output-examples.md for CSV format, sample outputs, and integration examples.
+
+### Customer Interview Analyzer
+
+NLP-based analysis extracting pain points, feature requests, JTBD patterns, sentiment, themes, and competitor mentions.
+
+```bash
+python scripts/customer_interview_analyzer.py interview.txt        # Text report
+python scripts/customer_interview_analyzer.py interview.txt json   # JSON output
+```
+
+## Common Pitfalls
+
+| Pitfall | Prevention |
+|---------|------------|
+| **Solution-First** | Start every PRD with problem statement |
+| **Analysis Paralysis** | Set time-boxes for research phases |
+| **Feature Factory** | Define success metrics before building |
+| **Ignoring Tech Debt** | Reserve 20% capacity for maintenance |
+| **Stakeholder Surprise** | Weekly async updates, monthly demos |
+| **Metric Theater** | Tie metrics to user value delivered |
+
+## Best Practices
+
+- **PRDs**: Start with problem, include success metrics, state out-of-scope, use visuals, version control
+- **Prioritization**: Mix quick wins with strategic bets, consider opportunity cost, buffer 20%, revisit quarterly
+- **Discovery**: Ask "why" five times, focus on past behavior, avoid leading questions, validate qual with quant
+
+## Reference Documents
+
+- `references/prd_templates.md` - PRD templates for different contexts
+- `references/frameworks.md` - RICE, MoSCoW, Kano, JTBD framework documentation
+- `references/input-output-examples.md` - Detailed I/O examples