diff --git a/recoup-research/SKILL.md b/recoup-research/SKILL.md new file mode 100644 index 0000000..a5d04f9 --- /dev/null +++ b/recoup-research/SKILL.md @@ -0,0 +1,168 @@ +--- +name: recoup-research +description: Music industry research via `recoup research` CLI — streaming metrics, audience demographics, playlist placements, competitive analysis, people search, URL extraction, structured enrichment, and web intelligence. Use when the user needs artist analytics, streaming numbers, audience insights, playlist tracking, similar artists, collaboration targets, tour routing data, or any music industry research. Also use for finding people in the industry (managers, A&R), extracting data from URLs, or enriching entities with structured web research. Triggers on requests involving Spotify followers, monthly listeners, TikTok trends, Instagram audience, playlist pitching, competitive analysis, "how is [artist] doing," "research [artist]," "find me [people]," or any question about an artist's performance, market position, or industry contacts. +--- + +# Recoup Research + +Music industry research through the `recoup research` CLI. All commands use `RECOUP_API_KEY` for auth. In sandboxes, this is already configured. + +## Before You Research + +1. Check if the artist has a workspace with `context/artist.md` — don't re-research what's already known. +2. Decide what the user actually needs. "How's Drake doing?" needs 2-3 commands, not 20. +3. Always use `--json` when you'll process the output programmatically. + +## Decision Tree + +Start here based on what the user asks: + +**"How is [artist] doing?"** → `metrics --source spotify` + `cities` + `insights` + +**"Research [artist] for me"** → Full chain: `profile` → parallel(`metrics`, `audience`, `cities`, `similar`, `playlists`) → `web` for narrative context → synthesize + +**"Who should I pitch to?"** → `similar --audience high --genre high` → `playlists` on each peer → find playlists that have peers but not your artist + +**"Where should we tour?"** → `cities` + `audience --platform youtube` + `festivals` + +**"Find me [people]"** → `people "A&R reps at [label]"` + +**"Tell me about [entity]"** → `enrich "[entity]" --schema '{...}'` for structured data, or `report "[entity]"` for a narrative + +**"What does this page say?"** → `extract "https://..."` + +**"Find emerging artists"** → `discover --country US --genre GENRE_ID --spotify-listeners 50000,200000` (get IDs from `recoup research genres`) + +If none of these match, start with `web "query"` for general research. + +--- + +## Commands Quick Reference + +### Artist Data (accept artist name, API resolves internally) + +```bash +recoup research "Drake" --json # search — returns { results: [{ name, id, sp_monthly_listeners, sp_followers }] } +recoup research profile "Drake" --json # full profile — { name, genres, country_code, cm_artist_score, ... } +recoup research metrics "Drake" --source spotify --json # time-series — { followers: [...], listeners: [...], popularity: [...] } +recoup research audience "Drake" --json # demographics — { audience_genders: [...], audience_genders_per_age: [...], top_countries: [...] } +recoup research cities "Drake" --json # geography — { cities: [{ name, country, listeners }] } +recoup research similar "Drake" --json # competitors — { artists: [{ name, career_stage, recent_momentum, sp_monthly_listeners }] } +recoup research playlists "Drake" --json # placements — { placements: [{ playlist: { name, followers }, track: { name } }] } +recoup research albums "Drake" --json # discography — { albums: [{ name, release_date }] } +recoup research tracks "Drake" --json # tracks — { tracks: [{ name, id }] } +recoup research career "Drake" --json # timeline — career milestones array +recoup research insights "Drake" --json # AI observations — { insights: [{ insight: "text" }] } +recoup research urls "Drake" --json # social links — { urls: [{ domain, url }] } +recoup research instagram-posts "Drake" --json # top posts/reels +``` + +### Non-Artist Data + +```bash +recoup research lookup "https://open.spotify.com/artist/..." --json +recoup research track "God's Plan" --json +recoup research playlist spotify 1645080 --json +recoup research curator spotify 1 --json +recoup research discover --country US --spotify-listeners 100000,500000 --json +recoup research genres --json +recoup research festivals --json +``` + +### Web Intelligence + +```bash +recoup research web "Drake brand partnerships" --json # web search — { results: [{ title, url, snippet }] } +recoup research report "Tell me about Drake" --json # deep research — { content: "markdown report", citations: [...] } +recoup research people "A&R reps at Atlantic Records" --json # people search — { results: [{ title, url, summary }] } +recoup research extract "https://example.com" --json # URL scraping — { results: [{ title, url, excerpts: [...] }] } +recoup research enrich "Drake" --schema '{"properties":{"label":{"type":"string"}}}' --json # structured — { output: { label: "OVO Sound" } } +``` + +### Platform Sources (for `metrics` command) + +`spotify`, `instagram`, `tiktok`, `twitter`, `facebook`, `youtube_channel`, `youtube_artist`, `soundcloud`, `deezer`, `twitch`, `line`, `melon`, `wikipedia`, `bandsintown` + +For **`metrics` only**, YouTube uses `youtube_channel` (not plain `youtube`). The **`audience`** command is different: Chartmetric’s path is `youtube-audience-stats`, so there you pass `--platform youtube` (see examples above). Do not use `youtube_channel` for `audience`. + +--- + +## Interpreting the Data + +Raw numbers are noise without interpretation. Here's what to look for: + +**Metrics:** +- Follower-to-listener ratio above 20% = dedicated fan base (they follow, not just stream) +- Save-to-listener ratio above 3% = strong catalog stickiness +- Week-over-week listener growth above 5% = momentum +- Popularity score trending up = algorithmic favor + +**Cities:** +- If top cities are international but playlists are US-only = untapped international opportunity +- If a city has high listeners but the artist has never toured there = tour opportunity +- Compare with similar artists' cities to find geographic white space + +**Similar Artists:** +- `career_stage`: undiscovered → developing → mid-level → mainstream → superstar → legendary +- `recent_momentum`: decline → gradual decline → steady → growth → explosive growth +- If the artist's peers are all "mainstream" but they're "mid-level" = breakout potential +- Peers with playlists you're NOT on = pitch targets + +**Playlists:** +- 2 editorial playlists for 5M+ listeners = severely under-playlisted (pitch immediately) +- Follower count on playlists tells you reach potential +- Past placements (`--status past`) that dropped off = re-pitch opportunities + +**Audience:** +- Gender skew tells you content strategy (visual style, messaging) +- Age concentration tells you platform priority (Gen Z = TikTok, 25-34 = Instagram) +- Country mismatch between audience and cities = content localization opportunity + +--- + +## Synthesis Patterns + +Don't dump raw data. Combine endpoints and draw conclusions: + +**Geographic Strategy:** `cities` + `audience` → "Sao Paulo is #1 (135K listeners) but audience is 80% US on Instagram. There's a massive Brazilian fan base that isn't being served with localized content." + +**Playlist Gap Analysis:** `similar` → `playlists` on each peer → "5 of your 10 peers are on 'R&B Rotation' (450K followers) but you're not. That's your top pitch target." + +**Platform Pipeline:** `metrics --source tiktok` + `metrics --source spotify` → "TikTok followers grew 40% last month but Spotify listeners are flat. The TikTok virality isn't converting. Need Spotify-specific CTAs on TikTok content." + +**Career Positioning:** `similar` → compare career stages → "You're the only 'mainstream' artist in your peer group — everyone else is 'mid-level'. You have positioning leverage for brand deals and festival slots." + +--- + +## Saving Research + +If working in an artist workspace, save research results to `research/` with timestamps: + +``` +research/artist-intel-2026-03-27.md +``` + +Don't overwrite `context/artist.md` with research data. Static context (who the artist IS) is separate from dynamic research (how they're performing NOW). If the research reveals something that should update the static profile, suggest it to the user — don't auto-update. + +--- + +## What Not to Do + +- **Don't run 20 commands when 3 will answer the question.** Start small, expand if needed. +- **Don't dump raw JSON to the user.** Interpret the data and draw conclusions. +- **Don't re-research what `context/artist.md` already covers.** Read it first. +- **Don't ignore the `--json` flag when chaining.** Tables are for humans, JSON is for you. +- **Don't assume Chartmetric has every artist.** If search returns no results, fall back to `web` or `report`. + +--- + +## Graceful Degradation + +If `recoup research "Artist Name"` returns no results: +1. Try `recoup research web "Artist Name musician"` for web-based research +2. Try `recoup research enrich "Artist Name" --schema '{...}'` for structured extraction +3. For very emerging artists, Chartmetric may not have data yet — web research is the fallback + +## More Workflows + +Read `references/workflows.md` for 10 complete multi-step workflow chains covering playlist pitching, competitive analysis, tour routing, A&R discovery, and more. diff --git a/recoup-research/references/workflows.md b/recoup-research/references/workflows.md new file mode 100644 index 0000000..ab93492 --- /dev/null +++ b/recoup-research/references/workflows.md @@ -0,0 +1,283 @@ +# Research Workflow Chains + +Multi-step workflows that chain `recoup research` commands to answer strategic questions. Each workflow tells you what to run, in what order, and what to look for in the results. + +--- + +## 1. Playlist Pitching Intelligence + +**Question:** "Which playlist curators should I pitch to?" + +```bash +# 1. Find similar artists who are slightly bigger (good benchmarks) +recoup research similar "{ARTIST}" --audience high --genre high --limit 50 --json + +# 2. For each similar artist, get their editorial playlist placements +recoup research playlists "{similar_artist}" --editorial --json + +# 3. Look for playlist overlap — curators who added multiple similar artists +# These curators are most likely to add your artist + +# 4. For promising playlists, get curator details +recoup research playlist spotify {playlist_id} --json +recoup research curator spotify {curator_id} --json + +# 5. Check if target artist was ever on these playlists before +recoup research playlists "{ARTIST}" --status past --json +``` + +**What to synthesize:** List of curators who already playlist similar artists but haven't added yours yet. Prioritize curators who've added 2+ similar artists — they're the warmest targets. + +--- + +## 2. TikTok-to-Spotify Pipeline Analysis + +**Question:** "Is TikTok virality translating to Spotify growth?" + +```bash +# 1. Get TikTok metrics over time +recoup research metrics "{ARTIST}" --source tiktok --json + +# 2. Get Spotify metrics over same period +recoup research metrics "{ARTIST}" --source spotify --json + +# 3. Get TikTok audience demographics +recoup research audience "{ARTIST}" --platform tiktok --json + +# 4. Get Spotify listener cities +recoup research cities "{ARTIST}" --json + +# 5. Get top Instagram posts (often cross-posted from TikTok) +recoup research instagram-posts "{ARTIST}" --json +``` + +**What to synthesize:** Correlation between TikTok follower spikes and Spotify listener growth. Geographic mismatch = opportunity (e.g., TikTok viral in Brazil but Spotify listeners mostly in US means Brazil is an untapped market). + +--- + +## 3. Tour Routing Intelligence + +**Question:** "Where should this artist tour next?" + +```bash +# 1. Get top listener cities +recoup research cities "{ARTIST}" --json + +# 2. Get festivals +recoup research festivals --json + +# 3. Find similar artists and their cities (for co-headlining opportunities) +recoup research similar "{ARTIST}" --audience high --limit 20 --json + +# 4. Get audience breakdown by platform and region +recoup research audience "{ARTIST}" --platform youtube --json +recoup research audience "{ARTIST}" --platform instagram --json + +# 5. Check playlist reach by geography +recoup research playlists "{ARTIST}" --sort followers --json +``` + +**What to synthesize:** Ranked cities by streaming engagement, cross-referenced with festival opportunities. Cities where similar artists tour successfully but this artist hasn't been = expansion opportunities. + +--- + +## 4. A&R Discovery + +**Question:** "Find emerging artists in [genre] before they blow up" + +```bash +# 1. Start with a breakout artist in the genre as anchor +recoup research "{ANCHOR_ARTIST}" --json + +# 2. Find artists similar by musicality (not audience — we want undiscovered) +recoup research similar "{ANCHOR_ARTIST}" --musicality high --genre high --limit 50 --json + +# 3. For promising candidates, check their trajectory +recoup research metrics "{candidate}" --source spotify --json +recoup research metrics "{candidate}" --source tiktok --json + +# 4. Check playlist traction (editorial placements = label interest signal) +recoup research playlists "{candidate}" --editorial --json + +# 5. Get AI insights +recoup research insights "{candidate}" --json +``` + +**What to synthesize:** Emerging artists with similar sound but smaller audience, sorted by growth velocity. Filter for career_stage "undiscovered" or "developing" in the similar artists response. + +--- + +## 5. Catalog Optimization + +**Question:** "Which songs should we push and where?" + +```bash +# 1. Get all tracks +recoup research tracks "{ARTIST}" --json + +# 2. Get playlist placements (which songs are playlisted?) +recoup research playlists "{ARTIST}" --json + +# 3. Get albums with release dates +recoup research albums "{ARTIST}" --json + +# 4. Get metrics to compare against release dates +recoup research metrics "{ARTIST}" --source spotify --json +recoup research metrics "{ARTIST}" --source tiktok --json +``` + +**What to synthesize:** Track-by-track analysis. Look for: +- High playlist reach but low streams = discovery issue (content isn't converting) +- Low playlist but high TikTok = pitch opportunity (organic momentum, needs editorial support) +- Old songs suddenly getting playlisted = catalog momentum (amplify it) + +--- + +## 6. Competitive Roster Analysis + +**Question:** "How does our roster compare to a competitor label?" + +```bash +# For each artist on your roster: + +# 1. Get profile and metrics +recoup research profile "{your_artist}" --json +recoup research metrics "{your_artist}" --source spotify --json + +# 2. Find similar artists (potential competitor roster) +recoup research similar "{your_artist}" --audience high --genre high --json + +# 3. Compare playlist reach +recoup research playlists "{your_artist}" --sort followers --json +recoup research playlists "{competitor_artist}" --sort followers --json + +# 4. Compare audience demographics +recoup research audience "{your_artist}" --json +recoup research audience "{competitor_artist}" --json + +# 5. Compare where fans listen +recoup research cities "{your_artist}" --json +recoup research cities "{competitor_artist}" --json +``` + +**What to synthesize:** Side-by-side comparison. Identify where your roster under-indexes vs competitors on specific metrics — those are the gaps to close. + +--- + +## 7. Viral Song Autopsy + +**Question:** "Why did this song go viral? Can we replicate it?" + +```bash +# 1. Get track details +recoup research track "{SONG_NAME_OR_URL}" --json + +# 2. Get metrics around release date +recoup research metrics "{ARTIST}" --source spotify --json +recoup research metrics "{ARTIST}" --source tiktok --json + +# 3. Check playlist placements timeline +recoup research playlists "{ARTIST}" --since 2025-01-01 --sort followers --json + +# 4. Get AI insights (may mention the viral moment) +recoup research insights "{ARTIST}" --json + +# 5. Check if similar artists had similar trajectory +recoup research similar "{ARTIST}" --musicality high --json +``` + +**What to synthesize:** Timeline of the viral moment — what platform it started on, which playlists amplified it, which audience demographics drove sharing. Compare with similar artists' trajectories to identify if the pattern is replicable. + +--- + +## 8. Market Expansion Scouting + +**Question:** "Which new markets should we focus on?" + +```bash +# 1. Current listener geography +recoup research cities "{ARTIST}" --json + +# 2. Platform-specific audience breakdown +recoup research audience "{ARTIST}" --json +recoup research audience "{ARTIST}" --platform tiktok --json +recoup research audience "{ARTIST}" --platform youtube --json + +# 3. Find similar artists and their top cities +recoup research similar "{ARTIST}" --genre high --limit 10 --json +# For each similar artist: +recoup research cities "{similar_artist}" --json + +# 4. Check playlist coverage in potential markets +recoup research playlists "{ARTIST}" --json +``` + +**What to synthesize:** Cities where similar artists thrive but the target artist is weak = expansion opportunities. Cross-reference with playlist coverage — markets with fans but no playlist presence need pitching. + +--- + +## 9. Collaboration Finder + +**Question:** "Which artists should we collaborate with?" + +```bash +# 1. Find artists with shared fanbase +recoup research similar "{ARTIST}" --audience high --limit 30 --json + +# 2. Find artists with genre/sound overlap +recoup research similar "{ARTIST}" --genre high --musicality high --json + +# 3. Compare playlist placements (shared playlists = easy collab pitch) +recoup research playlists "{ARTIST}" --editorial --json +recoup research playlists "{collab_target}" --editorial --json + +# 4. Compare geographic overlap (shared cities = tour collab opportunity) +recoup research cities "{ARTIST}" --json +recoup research cities "{collab_target}" --json +``` + +**What to synthesize:** Ranked collaboration targets by audience overlap, career stage (slightly bigger = ideal), and playlist synergy. Shared playlists + shared cities = strongest collab case. + +--- + +## 10. Release Strategy Timing + +**Question:** "When should we release, and how should we roll it out?" + +```bash +# 1. Analyze past releases +recoup research albums "{ARTIST}" --json +recoup research career "{ARTIST}" --json + +# 2. Check what worked — playlist adds after previous releases +recoup research playlists "{ARTIST}" --status past --since 2024-01-01 --json + +# 3. Look at similar artists' successful releases +recoup research similar "{ARTIST}" --audience high --limit 10 --json +recoup research albums "{similar_artist}" --json +recoup research career "{similar_artist}" --json + +# 4. Check current playlist momentum +recoup research playlists "{ARTIST}" --editorial --json + +# 5. Identify which platforms are hottest right now +recoup research metrics "{ARTIST}" --source spotify --json +recoup research metrics "{ARTIST}" --source tiktok --json +recoup research metrics "{ARTIST}" --source youtube_channel --json +``` + +**What to synthesize:** Release timing recommendation based on historical patterns (when did past releases get the most playlist adds?), similar artists' release cycles, and which platform has the most momentum right now. + +--- + +## Building Your Own Workflows + +The power is in combining data types: + +| What You Need | Command | Use For | +|---------------|---------|---------| +| **Who** — peers, competitors, collaborators | `similar` | Finding benchmarks, pitch targets, collab opportunities | +| **Where** — geographic data | `cities`, `audience` | Tour routing, market expansion, geographic strategy | +| **What** — content and catalog | `playlists`, `tracks`, `albums` | Content strategy, playlist pitching, catalog optimization | +| **When** — timing and trajectory | `metrics`, `career` | Release timing, growth analysis, trend detection | +| **Why** — context and narrative | `insights`, `web`, `report` | Cultural positioning, press strategy, brand partnerships | diff --git a/setup-sandbox b/setup-sandbox index 004e609..736a5a2 160000 --- a/setup-sandbox +++ b/setup-sandbox @@ -1 +1 @@ -Subproject commit 004e609a29beeda214622ebce11e46a09c1f7066 +Subproject commit 736a5a2b63b76744f09f6b4ba46152930ad56944