Skip to content

fix: rename report to deep in industry-research skill #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sidneyswift wants to merge 2 commits into
base: main
Choose a base branch
from
Open

fix: rename report to deep in industry-research skill #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e92f03a
fix: rename `report` to `deep` in industry-research skill to match CL…
sidneyswift Apr 5, 2026
9b800fd
fix: remove Chartmetric branding from skill — API is provider-agnostic
sidneyswift Apr 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 168 additions & 0 deletions recoup-research/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify stale narrative command references across skills docs.
rg -nP 'recoup research report|`report\b|or `report`' --type=md

Repository: recoupable/skills

Length of output: 512

🏁 Script executed:

# Check if industry-research SKILL.md exists and uses `deep`
fd -t f "SKILL.md" | head -20

Repository: recoupable/skills

Length of output: 422

🏁 Script executed:

# Look for `deep` command usage in skills documentation
rg -nP '`deep\b|recoup research deep' --type=md

Repository: recoupable/skills

Length of output: 711

🏁 Script executed:

# Check for any CLI or main documentation about the rename
fd -t f "README|CHANGELOG|\.md" | xargs rg -l "report|deep" | head -10

Repository: recoupable/skills

Length of output: 367

🏁 Script executed:

# Compare the two SKILL.md files to understand the relationship
echo "=== recoup-research/SKILL.md (lines 25-35) ===" && sed -n '25,35p' recoup-research/SKILL.md
echo -e "\n=== skills/industry-research/SKILL.md (lines 25-35) ===" && sed -n '25,35p' skills/industry-research/SKILL.md

Repository: recoupable/skills

Length of output: 1116

🏁 Script executed:

# Check file creation/modification context and directory structure
echo "=== Directory structure ===" && ls -la recoup-research/ | head -10 && echo "---" && ls -la skills/industry-research/ | head -10

Repository: recoupable/skills

Length of output: 496

Update report command references to deep in recoup-research/SKILL.md.

Lines 30, 76, and 155 document the stale report command, which conflicts with the updated skills/industry-research/SKILL.md that uses deep. Update all three occurrences:

Required changes 
-**"Tell me about [entity]"** → `enrich "[entity]" --schema '{...}'` for structured data, or `report "[entity]"` for a narrative
+**"Tell me about [entity]"** → `enrich "[entity]" --schema '{...}'` for structured data, or `deep "[entity]"` for a narrative
-recoup research report "Tell me about Drake" --json          # deep research — { content: "markdown report", citations: [...] }
+recoup research deep "Tell me about Drake" --json            # deep research — { content: "markdown report", citations: [...] }
-- **Don't assume Chartmetric has every artist.** If search returns no results, fall back to `web` or `report`.
+- **Don't assume Chartmetric has every artist.** If search returns no results, fall back to `web` or `deep`.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@recoup-research/SKILL.md` at line 30, Update the stale command references in
recoup-research/SKILL.md by replacing every occurrence of the `report
"[entity]"` invocation with `deep "[entity]"` (three instances noted), and
adjust any adjacent explanatory text if it explicitly names the old `report`
command so it matches the new `deep` usage; search for the literal `report
"[entity]"` and update to `deep "[entity]"` to keep this file consistent with
skills/industry-research/SKILL.md.

Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai bot Apr 5, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: This report was not renamed to deep. The PR description explicitly lists this as one of the 4 references to update, but the change was not applied.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At recoup-research/SKILL.md, line 30:

<comment>This `report` was not renamed to `deep`. The PR description explicitly lists this as one of the 4 references to update, but the change was not applied.</comment>

<file context>
@@ -0,0 +1,168 @@
+
+**"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://..."` 
</file context>
Fix with Cubic


**"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: [...] }
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai bot Apr 5, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: This report command was not renamed to deep. The PR description lists this as one of the 4 references to update, but the change was not applied. The comment even says "# deep research" while the command itself still says report.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At recoup-research/SKILL.md, line 76:

<comment>This `report` command was not renamed to `deep`. The PR description lists this as one of the 4 references to update, but the change was not applied. The comment even says "# deep research" while the command itself still says `report`.</comment>

<file context>
@@ -0,0 +1,168 @@
+
+```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: [...] }] }
</file context>
Fix with Cubic

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
```
Comment on lines +141 to +143
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add a language to the fenced code block (markdownlint MD040).

This block is missing a language identifier; markdownlint will keep warning on it.

Suggested doc fix 
-```
+```text
 research/artist-intel-2026-03-27.md
</details>

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.22.0)</summary>

[warning] 141-141: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @recoup-research/SKILL.md around lines 141 - 143, The fenced code block in
SKILL.md is missing a language identifier (markdownlint MD040); update the
backticks for the block that contains "research/artist-intel-2026-03-27.md" to
include a language tag (e.g. change totext or ```md) so markdownlint
stops warning and the file renders with the intended code block language.


</details>

<!-- fingerprinting:phantom:triton:hawk:b914894e-5b27-4eef-b7bf-9ea5ace4bc71 -->

<!-- This is an auto-generated comment by CodeRabbit -->


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`.
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai bot Apr 5, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: This report was not renamed to deep. The PR description lists this as one of the 4 references to update, but the change was not applied.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At recoup-research/SKILL.md, line 155:

<comment>This `report` was not renamed to `deep`. The PR description lists this as one of the 4 references to update, but the change was not applied.</comment>

<file context>
@@ -0,0 +1,168 @@
+- **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`.
+
+---
</file context>
Fix with Cubic


---

## 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.
10 changes: 5 additions & 5 deletions skills/industry-research/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Start here based on what the user asks:

**"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
**"Tell me about [entity]"** → `enrich "[entity]" --schema '{...}'` for structured data, or `deep "[entity]"` for a narrative

**"What does this page say?"** → `extract "https://..."`

Expand Down Expand Up @@ -73,7 +73,7 @@ recoup research festivals --json

```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 deep "Tell me about Drake" --json # deep research — { content: "markdown report", citations: [...] }
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Rename lingering “report” wording in deep example output.

The command is correctly renamed to deep, but the inline output description still says markdown report, which reintroduces old terminology. Consider changing it to neutral wording like markdown narrative for consistency.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@skills/industry-research/SKILL.md` at line 76, Update the inline output
description for the `deep` example invocation so it no longer uses the old term
"markdown report"; locate the example line containing `recoup research deep
"Tell me about Drake" --json` in SKILL.md and replace the `markdown report`
wording with a neutral term such as `markdown narrative` (or another preferred
synonym) so the example output description matches the renamed `deep` command.

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" } }
Expand All @@ -83,7 +83,7 @@ recoup research enrich "Drake" --schema '{"properties":{"label":{"type":"string"

`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`.
For **`metrics` only**, YouTube uses `youtube_channel` (not plain `youtube`). The **`audience`** command is different — pass `--platform youtube` (see examples above). Do not use `youtube_channel` for `audience`.

---

Expand Down Expand Up @@ -152,7 +152,7 @@ Don't overwrite `context/artist.md` with research data. Static context (who the
- **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`.
- **Don't assume every artist has data.** If search returns no results, fall back to `web` or `deep`.

---

Expand All @@ -161,7 +161,7 @@ Don't overwrite `context/artist.md` with research data. Static context (who the
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
3. For very emerging artists, structured data may not exist yet — web research is the fallback

## More Workflows

Expand Down
2 changes: 1 addition & 1 deletion skills/industry-research/references/workflows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,4 +280,4 @@ The power is in combining data types:
| **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 |
| **Why** — context and narrative | `insights`, `web`, `deep` | Cultural positioning, press strategy, brand partnerships |