@crowdlisten/harness 1.0.0

package/skills/data-storytelling/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: crowdlisten:data-storytelling
+description: Transform data and analysis into compelling narratives. Problem-Solution, Trend, Comparison, Hero's Journey frameworks. Use when presenting insights to stakeholders.
+user-invocable: true
+allowed-tools: Bash, Read, Write, WebFetch, Grep
+metadata:
+  openclaw:
+    category: data
+    tags: [data-storytelling, narrative, visualization, executive-communication]
+    requires_api_key: false
+---
+
+# Data Storytelling
+
+Transform raw data and analysis into compelling, memorable narratives that drive action and understanding.
+
+## Before You Start
+
+Ask your human for business context — this skill produces significantly better output when grounded in specifics:
+
+- **Target market**: Who are the customers? What industry/segment?
+- **Key competitors**: Which brands or products to compare against?
+- **Constraints**: Budget, timeline, geographic focus?
+- **Decision context**: What decisions will this analysis inform? (roadmap, funding, positioning, hiring?)
+- **Existing data**: Any prior research, internal metrics, or hypotheses to validate?
+
+## Capabilities
+
+This skill enables:
+- **Narrative Construction**: Build compelling stories from data
+- **Framework Application**: Problem-Solution, Trend, Comparison, and more
+- **Audience Adaptation**: Tailor stories for different stakeholders
+- **Visual Storytelling**: Design supporting data visualizations
+- **Executive Communication**: Synthesize for C-suite presentations
+
+## Story Frameworks
+
+### Problem-Solution Framework
+Structure data around a challenge and its resolution:
+
+```markdown
+## The Challenge
+[Present the problem with data that shows its magnitude and urgency]
+
+## The Impact
+[Quantify the consequences - what happens if nothing changes]
+
+## The Insight
+[The "aha moment" - what the data revealed]
+
+## The Solution
+[Data-backed approach to solving the problem]
+
+## The Outcome
+[Projected or actual results with supporting metrics]
+```
+
+### Trend Narrative Framework
+Tell the story of change over time:
+
+```markdown
+## Where We Were
+[Historical baseline - establish the starting point with data]
+
+## The Catalyst
+[What changed - the inflection point or driving event]
+
+## The Trajectory
+[How things evolved - show the trend with data points]
+
+## Where We're Heading
+[Future projection based on current trajectory]
+
+## What It Means
+[Implications and recommended actions]
+```
+
+### Comparison Framework
+Illuminate differences to drive decisions:
+
+```markdown
+## The Options
+[Present what's being compared]
+
+## The Criteria
+[Establish the basis for comparison]
+
+## The Analysis
+[Side-by-side data comparison]
+
+## The Winner
+[Clear recommendation with data justification]
+
+## The Caveats
+[Limitations and context for the comparison]
+```
+
+### Hero's Journey Framework
+Cast the audience/customer as the protagonist:
+
+```markdown
+## The Ordinary World
+[Current state - where the hero starts]
+
+## The Call to Adventure
+[The challenge or opportunity presenting itself]
+
+## The Challenges
+[Obstacles and data showing difficulty]
+
+## The Transformation
+[How the solution changed things]
+
+## The Return
+[New normal with quantified improvements]
+```
+
+## Narrative Elements
+
+### The Hook
+Open with something surprising, challenging, or emotionally resonant:
+- Counterintuitive statistic
+- Provocative question
+- Relatable scenario
+- Bold statement
+
+### The Build
+Develop understanding progressively:
+- Context and background
+- Supporting evidence
+- Building complexity
+- Addressing objections
+
+### The Payoff
+Deliver the insight with impact:
+- Clear conclusion
+- Actionable recommendations
+- Memorable takeaway
+- Call to action
+
+## Story Templates
+
+### Executive Summary Story
+```markdown
+# [Compelling Title]
+
+## Key Finding
+[One sentence that captures the essential insight]
+
+## Why It Matters
+[2-3 sentences on business impact]
+
+## The Evidence
+[3-5 supporting data points]
+
+## Recommended Action
+[Clear next step with timeline]
+
+## If We Don't Act
+[Risk of inaction with data]
+```
+
+### Insight Narrative
+```markdown
+# [Insight Title]
+
+## The Discovery
+[What we found and why it's significant]
+
+## The Story Behind the Numbers
+[Context that brings data to life]
+
+## What the Data Shows
+### Finding 1: [Title]
+[Evidence with visualization]
+
+### Finding 2: [Title]
+[Evidence with visualization]
+
+### Finding 3: [Title]
+[Evidence with visualization]
+
+## The Bigger Picture
+[How this connects to broader trends/goals]
+
+## What This Means for You
+[Personalized implications for the audience]
+
+## Next Steps
+[Actionable recommendations]
+```
+
+### Trend Report Story
+```markdown
+# [Trend Title]: What the Data Tells Us
+
+## The Headline
+[Attention-grabbing summary statistic]
+
+## The Backstory
+[How we got here]
+
+## The Current State
+[Present situation with data]
+
+## The Trajectory
+[Where things are heading]
+
+## The Drivers
+[What's causing this trend]
+
+## The Opportunities
+[How to capitalize]
+
+## The Risks
+[What to watch out for]
+
+## The Bottom Line
+[Key takeaway for decision-makers]
+```
+
+## Visualization Principles
+
+### Choose the Right Chart
+| Data Type | Recommended Visualization |
+|-----------|--------------------------|
+| Trends over time | Line chart, area chart |
+| Part-to-whole | Pie chart, stacked bar |
+| Comparisons | Bar chart, grouped bar |
+| Distribution | Histogram, box plot |
+| Relationships | Scatter plot, bubble chart |
+| Geographic | Map, choropleth |
+
+### Design Guidelines
+1. **Title tells the story**: Not "Sales by Region" but "Western Region Leads Growth"
+2. **Highlight the insight**: Use color/size to draw attention
+3. **Remove clutter**: Every element should serve a purpose
+4. **Provide context**: Include benchmarks, targets, or comparisons
+5. **Make it accessible**: Consider colorblind-friendly palettes
+
+## Integration with CrowdListen
+
+This skill enhances CrowdListen by:
+- Transforming social listening analyses into executive narratives
+- Creating compelling stories from community sentiment data
+- Designing presentations that communicate crowd insights effectively
+- Adapting technical findings for non-technical stakeholders
+- Building persuasive cases from user feedback and opinions

package/skills/heuristic-evaluation/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: crowdlisten:heuristic-evaluation
+description: Customer feedback analysis from social conversations. Journey friction detection, pain point mapping, persona generation, churn risk signals. Requires CROWDLISTEN_API_KEY.
+user-invocable: true
+allowed-tools: Bash, Read, Write, WebFetch, Grep
+metadata:
+  openclaw:
+    category: research
+    tags: [customer-feedback, journey-analysis, pain-points, churn-risk]
+    requires_api_key: true
+---
+
+# Heuristic Evaluation
+
+Every conversation is customer research. Extract structured UX and CX insights from social discussions using CrowdListen audience intelligence.
+
+Consolidates: voice-of-customer, audience-discovery (persona generation, community mapping)
+
+## Before You Start
+
+Ask your human for business context — this skill produces significantly better output when grounded in specifics:
+
+- **Target market**: Who are the customers? What industry/segment?
+- **Key competitors**: Which brands or products to compare against?
+- **Constraints**: Budget, timeline, geographic focus?
+- **Decision context**: What decisions will this analysis inform? (roadmap, funding, positioning, hiring?)
+- **Existing data**: Any prior research, internal metrics, or hypotheses to validate?
+
+## When to Use This Skill
+
+- Customer experience analysis and improvement
+- Journey friction detection and optimization
+- Feedback clustering and pain point mapping
+- Usability signal detection from organic discussions
+- Support strategy and ticket deflection
+- Customer health monitoring and churn prevention
+- Identifying and profiling target audience segments
+
+## Foundation: CrowdListen Tools
+
+This skill builds on CrowdListen's core capabilities:
+- `search_content` — Find customer discussions and feedback
+- `analyze_content` — Extract sentiment and themes from feedback
+- `cluster_opinions` — Group feedback into actionable categories
+- `get_content_comments` — Mine comment threads for detailed feedback
+- `sentiment_evolution_tracker` — Track satisfaction trends over time
+- `expert_identification` — Find key opinion leaders in communities
+
+## Workflows
+
+### 1. Journey Friction Detection
+
+Identify where in the customer journey users experience friction.
+
+**Process**:
+1. Search for stage-specific frustration signals:
+   - Discovery: "how do I find", "confusing options"
+   - Onboarding: "setup", "getting started", "first time"
+   - Core usage: "every time I try to", "should be easier"
+   - Expansion: "upgrade", "pricing", "worth paying for"
+   - Renewal/Churn: "canceling", "alternative", "leaving"
+2. Map friction points to journey stages
+3. Score by impact on conversion/retention
+
+**Output Template**:
+```markdown
+## Journey Friction Map
+
+| Stage | Friction Points | Severity | Volume | Impact |
+|-------|----------------|----------|--------|--------|
+| Discovery | [friction] | [H/M/L] | [count] | [conversion loss est.] |
+| Onboarding | [friction] | [H/M/L] | [count] | [activation loss est.] |
+| Core Usage | [friction] | [H/M/L] | [count] | [engagement loss est.] |
+
+### Biggest Friction: [Stage — Problem]
+**What users say**: [synthesis with quotes]
+**Why it matters**: [business impact]
+**Recommended fix**: [specific action]
+```
+
+### 2. Feedback Clustering
+
+Group unstructured customer feedback into actionable themes.
+
+**Process**:
+1. Search for product mentions with sentiment indicators
+2. Use `cluster_opinions` to group by root theme (not surface keywords)
+3. Score each cluster by: volume, severity, trend direction
+4. Map clusters to product areas and responsible teams
+
+**Output Template**:
+```markdown
+## Feedback Clusters — [Period]
+
+### Cluster 1: [Theme Name] (Severity: Critical)
+- **Volume**: X mentions across Y platforms
+- **Trend**: [rising/stable/declining] over [period]
+- **Product area**: [Onboarding / Core UX / Pricing / Performance / Support]
+- **Representative quotes**:
+  > "[Quote 1]" — [platform, engagement count]
+- **Action**: [Specific recommendation]
+
+### Summary Table
+| Theme | Volume | Severity | Trend | Owner | Status |
+|-------|--------|----------|-------|-------|--------|
+| [Theme] | [count] | [Crit/Imp/Mon] | [arrow] | [team] | [New/Known/WIP] |
+```
+
+### 3. Pain Point Mapping
+
+Cluster user frustrations into addressable product problems.
+
+**Process**:
+1. Search for negative sentiment discussions about your product/category
+2. Use `cluster_opinions` to group by root cause, not symptom
+3. Map clusters to product areas (onboarding, core UX, pricing, performance, etc.)
+
+**Output Template**:
+```markdown
+## Pain Point Map
+
+### Critical (High frequency + High severity)
+**[Pain Point Cluster Name]**
+- Affected area: [Product area]
+- Frequency: [X mentions/week]
+- Severity: [Users leaving / Users complaining / Users working around]
+- Root cause hypothesis: [Why this happens]
+- Example quotes:
+  > "[quote]" — [platform, date]
+
+### Important (High frequency OR High severity)
+[Same structure]
+```
+
+### 4. Data-Driven Persona Generation
+
+Create personas from real social discussions, not assumptions.
+
+**Process**:
+1. Search for your product category across platforms
+2. Analyze discussants' language, concerns, goals, and context clues
+3. Cluster into distinct persona groups by behavior patterns
+4. Validate against engagement patterns
+
+**Output Template**:
+```markdown
+## Audience Personas — [Category]
+
+### Persona 1: [Name] — "[One-line description]"
+**Archetype**: [Role/behavior archetype]
+**Estimated segment size**: [% of audience]
+
+**Goals**:
+1. [Primary goal with evidence from social discussions]
+
+**Pain Points**:
+1. [Frustration with evidence]
+
+**Behavior Patterns**:
+- Platforms: [Where they're most active]
+- Content preference: [What they engage with]
+- Decision process: [How they evaluate products]
+
+**Representative Quote**:
+> "[Actual quote from social discussions]"
+```
+
+### 5. Churn Risk Signals
+
+Detect early warning signs that customers may leave.
+
+**Process**:
+1. Search for switching discussions, alternative evaluations, frustration escalation
+2. Identify churn precursor patterns
+3. Score current churn risk level based on signal volume and trend
+
+**Output Template**:
+```markdown
+## Churn Risk Dashboard — [Period]
+
+**Overall Risk Level**: [Low / Moderate / Elevated / High]
+
+### Active Churn Signals
+| Signal Type | Volume | Trend | Severity |
+|-------------|--------|-------|----------|
+| Competitor comparison shopping | [count] | [up/down] | [H/M/L] |
+| "Alternative to [product]" searches | [count] | [up/down] | [H/M/L] |
+
+### Retention Recommendations
+- **Quick win**: [action that could immediately reduce churn risk]
+- **Strategic fix**: [larger initiative to address root cause]
+```
+
+## Integration with CrowdListen
+
+This skill enhances CrowdListen analyses by:
+- Providing structured UX/CX reports from unstructured social data
+- Detecting journey friction before it shows in retention metrics
+- Creating research-backed audience profiles from real social data
+- Connecting social sentiment to customer journey stages
+- Enabling continuous customer health monitoring without surveys

package/skills/market-research-reports/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: crowdlisten:market-research
+description: Generate comprehensive market research reports with Porter's Five Forces, PESTLE, SWOT, TAM/SAM/SOM, BCG Matrix. Use for market analysis, competitive landscape, industry trends.
+user-invocable: true
+allowed-tools: Bash, Read, Write, WebFetch, Grep
+metadata:
+  openclaw:
+    category: research
+    tags: [market-research, porters-five-forces, swot, tam-sam-som]
+    requires_api_key: false
+---
+
+# Market Research Reports
+
+Generate comprehensive, analyst-grade market research reports using established strategic frameworks and methodologies.
+
+## Before You Start
+
+Ask your human for business context — this skill produces significantly better output when grounded in specifics:
+
+- **Target market**: Who are the customers? What industry/segment?
+- **Key competitors**: Which brands or products to compare against?
+- **Constraints**: Budget, timeline, geographic focus?
+- **Decision context**: What decisions will this analysis inform? (roadmap, funding, positioning, hiring?)
+- **Existing data**: Any prior research, internal metrics, or hypotheses to validate?
+
+## Capabilities
+
+This skill enables generation of:
+- **Comprehensive Market Analysis**: 50+ page detailed reports
+- **Strategic Framework Application**: Porter's Five Forces, PESTLE, SWOT, BCG Matrix
+- **Market Sizing**: TAM/SAM/SOM calculations with methodology
+- **Competitive Intelligence**: Competitor profiling and positioning analysis
+- **Trend Analysis**: Industry trends, growth drivers, and future outlook
+
+## Core Frameworks
+
+### Porter's Five Forces
+Analyze competitive intensity and attractiveness of a market:
+1. **Threat of New Entrants**: Barriers to entry, capital requirements
+2. **Bargaining Power of Suppliers**: Supplier concentration, switching costs
+3. **Bargaining Power of Buyers**: Buyer concentration, price sensitivity
+4. **Threat of Substitutes**: Alternative products, switching costs
+5. **Competitive Rivalry**: Number of competitors, industry growth rate
+
+### PESTLE Analysis
+Macro-environmental factors affecting the market:
+- **Political**: Government policies, trade regulations, political stability
+- **Economic**: GDP growth, inflation, exchange rates, unemployment
+- **Social**: Demographics, cultural trends, consumer behavior
+- **Technological**: Innovation, R&D, automation, digital transformation
+- **Legal**: Regulatory frameworks, compliance requirements, IP laws
+- **Environmental**: Sustainability, climate impact, environmental regulations
+
+### SWOT Analysis
+Internal and external factor assessment:
+- **Strengths**: Internal capabilities and competitive advantages
+- **Weaknesses**: Internal limitations and areas for improvement
+- **Opportunities**: External favorable conditions and growth potential
+- **Threats**: External challenges and competitive risks
+
+### TAM/SAM/SOM Market Sizing
+- **Total Addressable Market (TAM)**: Total market demand
+- **Serviceable Addressable Market (SAM)**: Portion you can target
+- **Serviceable Obtainable Market (SOM)**: Realistic market capture
+
+### BCG Growth-Share Matrix
+Portfolio analysis for multi-product/segment evaluation:
+- **Stars**: High growth, high market share
+- **Cash Cows**: Low growth, high market share
+- **Question Marks**: High growth, low market share
+- **Dogs**: Low growth, low market share
+
+## Report Structure
+
+### Standard Market Research Report
+
+```markdown
+# [Industry/Market] Research Report
+
+## Executive Summary
+- Key findings
+- Market size and growth
+- Critical success factors
+- Strategic recommendations
+
+## Market Overview
+- Market definition and scope
+- Historical development
+- Current state of the market
+
+## Market Size & Forecast
+- TAM/SAM/SOM analysis
+- Growth projections (5-year)
+- Regional breakdown
+
+## Industry Analysis
+### Porter's Five Forces
+[Detailed analysis of each force]
+
+### PESTLE Analysis
+[Macro-environmental factors]
+
+## Competitive Landscape
+- Major players and market share
+- Competitive positioning map
+- Competitor profiles
+
+## Customer Analysis
+- Customer segments
+- Buying behavior
+- Unmet needs
+
+## Trends & Drivers
+- Key market trends
+- Growth drivers
+- Inhibitors and challenges
+
+## SWOT Analysis
+[Internal/external factors]
+
+## Strategic Recommendations
+- Market entry strategies
+- Competitive positioning
+- Investment priorities
+
+## Appendix
+- Data sources
+- Methodology
+- Definitions
+```
+
+## Usage
+
+### Generate Market Research Report
+
+```python
+# Example: Request a market research report
+await generate_market_report(
+    industry="Electric Vehicle Charging Infrastructure",
+    geography="North America",
+    depth="comprehensive",  # comprehensive | executive | segment
+    frameworks=["porters", "pestle", "swot", "tam_sam_som"]
+)
+```
+
+### Analyze Competitive Landscape
+
+```python
+# Example: Competitive analysis
+await analyze_competitors(
+    market="SaaS Project Management Tools",
+    competitors=["Asana", "Monday.com", "Notion", "ClickUp"],
+    dimensions=["pricing", "features", "market_position", "growth"]
+)
+```
+
+### Market Sizing
+
+```python
+# Example: Calculate TAM/SAM/SOM
+await calculate_market_size(
+    product="AI-powered Customer Service Platform",
+    target_segment="Mid-market B2B SaaS",
+    geography="Global",
+    methodology="bottom_up"  # bottom_up | top_down | value_based
+)
+```
+
+## Output Quality Standards
+
+1. **Data-Driven**: All claims supported by data sources
+2. **Cited Sources**: Academic, industry reports, and primary research
+3. **Actionable Insights**: Strategic recommendations with clear rationale
+4. **Visual Support**: Charts, graphs, and matrices where applicable
+5. **Professional Format**: Executive-ready presentation quality
+
+## Integration with CrowdListen
+
+This skill enhances CrowdListen analyses by:
+- Providing market context for social listening insights
+- Connecting community sentiment to industry trends
+- Enabling competitive intelligence from social data
+- Supporting strategic decision-making with comprehensive research