discover

Category: Tools & Productivity | Uploader: marcmuon | Downloads: 0 | Version: v1.0（Latest）

Seed-driven music discovery for the `cosine-digger` CLI. Use when working in the `cosine-club-digger` repo and the user wants one obvious workflow: give seeds, get a useful ranked table, and optionally make a playlist without remembering the full CLI surface. Accepts Discogs artist/label/release URLs, cosine playlist or track URLs, track text, and mixed seed baskets. Uses adaptive branching only when the baseline path is weak or ambiguous.

Changelog: Source: GitHub https://github.com/marcmuon/cosine-club-digger

Directory Structure

Current level: skills/cosine-digger-discover/

📁 agents/
- 📄 openai.yaml 210 B
📁 references/
- 📄 heuristics.md 3.1 KB
- 📄 probe-playbook.md 3.6 KB
- 📄 profile-format.md 601 B
📁 scripts/
- 📄 discogs_probe.py 7.2 KB
📄 SKILL.md 7.7 KB

SKILL.md

---
name: "discover"
description: "Seed-driven music discovery for the `cosine-digger` CLI. Use when working in the `cosine-club-digger` repo and the user wants one obvious workflow: give seeds, get a useful ranked table, and optionally make a playlist without remembering the full CLI surface. Accepts Discogs artist/label/release URLs, cosine playlist or track URLs, track text, and mixed seed baskets. Uses adaptive branching only when the baseline path is weak or ambiguous."
---

# /discover - Seed-Driven Music Discovery

Use this skill from the repo root.

Treat this skill as the main discovery UX:

- start from seeds
- run one obvious baseline command
- return one useful ranked table
- preserve the playlist path when asked
- use branch diagnostics only when they add value

Do not invent a new recommender inside the skill. Use the existing CLI first.

Load [references/probe-playbook.md](references/probe-playbook.md) when the baseline is weak, the prompt is mixed, or you need branch ideas.

Load [references/profile-format.md](references/profile-format.md) only if the user explicitly wants personalized digging or a local profile file exists.

## Core rules

- Start with one baseline command using the existing CLI.
- Preserve the current CLI mental model: ranked table first, playlist optional.
- Prefer small first passes before expensive deep runs. Default size is `--limit 8` to `12`.
- Prefer centroid mode first. Use intersection only after the branch already shows overlap.
- Verify the CLI's printed `Resolved:` lines when using text seeds.
- If a path looks bad, say so and pivot.
- Keep the workflow generic. Personal taste memory is optional and only a tie-breaker.
- Never present branch output as special unless it differs meaningfully from the baseline.
- If all viable branches converge to the same neighborhood, say so plainly and return the baseline or best equivalent table.

## Default flow

Use this sequence unless the user asks for something more exhaustive:

1. one obvious baseline run
2. up to two alternate branches if the baseline is weak or ambiguous
3. then either present the winning result table or ask for one more anchor

Avoid long autonomous wandering when no branch has proven it improves on baseline.

## Workflow

### 1. Parse anchors and modifiers

Classify each input:

- Discogs artist URL
- Discogs label URL
- Discogs release or master URL
- cosine.club playlist ID or track URL
- track text in `Artist - Track` form
- YouTube, SoundCloud, or Bandcamp URL
- modifiers like `obscure`, `deep`, `90s`, `cheap`, `tighter`, `surprise me`

If the user gives only vague taste language and no anchors, ask for 1-3 anchors before running anything.

### 2. Run the obvious baseline command

Pick the simplest reasonable command for the dominant anchor:

- artist URL: `artist-dig`
- label URL: `label-dig`
- release URL: `dig <release-url>`
- playlist ID: `playlist-dig`
- track texts or mixed audio URLs: `dig`
- mixed artist + label: run one artist probe and one label probe separately

Default settings:

- add `--deep` unless the user explicitly wants a quick check
- keep centroid mode
- start with `--limit 8` to `12`
- use `--max-seeds 8` to `12` for artist and label probes

If the user explicitly wants a playlist, include `--youtube` and a sensible `--playlist-name`.

Translate modifiers into flags:

- `obscure`, `deep`, `underground`: add `--deep`; consider `--collectors-max 300` to `800`
- `cheap`, `budget`: add `--price-max`
- `rare`, `grail`, `coveted`: add `--price-min` or `--want-min`
- decade or year language: add `--year-min` and `--year-max`
- `tighter`, `exact`, `in the overlap`: keep this in reserve for later intersection or branch tightening

### 3. Score the baseline before branching

Treat the first run as both result set and diagnostic.

Strong baseline:

- multiple resolved seeds
- several results with `# >= 2`
- centroid scores meaningfully above `1.0`
- clean `Resolved:` lines

Weak baseline:

- fewer than 3 useful seeds resolve
- top results are mostly `# = 1`
- intersection collapses to nothing
- text seeds resolve to sibling tracks instead of the requested one
- label or release path looks too small, too self-titled, or too fuzzy

If the baseline is strong and the user did not ask for deeper exploration, stop and return it.

If the baseline is weak, do not keep hammering the same command. Inspect structure and branch.

### 4. Inspect Discogs structure when the branch is weak

Use the bundled probe utility:

```bash
uv run python skills/cosine-digger-discover/scripts/discogs_probe.py "<discogs-url>" --limit 10 --with-cosine
```

Use it to answer:

- how large is this artist or label actually
- which releases exist nearby
- which releases resolve cleanly through cosine search
- whether the current path is thin because the source is small or because indexing is poor
- which artists, tracks, or credits are the best branch candidates

For non-Discogs seeds, use the CLI's `search` and `lookup` commands as the equivalent structural probe.

### 5. Generate alternate branches only when justified

Generate 2-3 alternate seed baskets from structure, not vibes.

For a weak label branch, try:

- the most promising label artist via `artist-dig`
- a manual `dig` built from the label's resolved tracks plus one outside anchor
- a branch centered on a credited collaborator, producer, or remix relation if present

For a weak artist branch, try:

- a smaller basket of the artist's strongest indexed tracks
- one branch through recurring labels
- one branch through appearances, remixes, or production lineage

For a weak release branch, try:

- direct release `dig`
- `producer-dig`
- track-level seeds from the release

For mixed prompts, bridge through the graph:

- run separate probes first
- take 2-3 clean, high-signal tracks from each side
- build one centroid bridge basket

### 6. Re-probe branches in parallel

Run alternate branches with small limits first.

Compare branches by:

- resolved seed count
- number of results with `# >= 2`
- score distribution
- resolution cleanliness
- whether the branch is clearly collapsing into noise
- whether the branch yields results outside the baseline top set

Prefer the branch that is structurally strongest, not the branch that merely contains one familiar artist.

### 7. Refine only after a branch proves it beats baseline

Once one branch clearly wins:

1. keep 2-4 diverse high-signal tracks
2. run a second-pass `dig ... --deep --limit 12` to `20`
3. use `--mode intersection` only if the branch already has strong overlap

Do not refine a weak branch.

### 8. Ask for calibration early when needed

If the top two branches are both weak or ambiguous, ask the user for one more anchor or a quick hit/miss read.

Good calibration questions:

- which 1-2 tracks are actual hits
- which 1-2 tracks are clearly wrong
- whether the branch is too airy, too obvious, too functional, too clean, too expensive, or too recent

Use that feedback to choose the next branch, not to rewrite the generic skill.

## Optional personal profile

If a profile file exists and the user wants personalized digging, use it only after a branch has already proven viable.

Allowed use:

- tie-break between two viable branches
- pick which second-pass basket to refine
- phrase follow-up questions more efficiently

Disallowed use:

- hard-filter the first probe
- suppress structurally strong branches before probing
- bake one user's profile into the shared skill

## Output contract

When reporting back:

- present one final ranked result set
- say whether it came from the baseline path or a branch
- if a branch won, say why the baseline was weak and why the branch was better
- if branches did not improve on baseline, say that explicitly
- include the exact commands that mattered
- keep the table mental model and note the playlist-ready command when relevant

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

discover

Directory Structure

SKILL.md

Report

Notice