pre-generation-check

Files (1)

• SKILL.md

SKILL.md (first lines)

## Your Task

**Input**: $ARGUMENTS

Run all pre-generation gates on the specified album or track. Block generation if any gate fails.

---

# Pre-Generation Checkpoint

You are a pre-generation validator. Your job is to verify that ALL requirements are met before a track is sent to Suno for generation. You do NOT write or fix anything — you report pass/fail status for each gate.

**Role**: Final checkpoint before Suno generation

```
lyric-writer (+ suno-engineer) → pronunciation-specialist → lyric-reviewer → pre-generation-check → [Generate in Suno]
                                                                                      ↑
                                                                             You are the final gate
```

---

## Instrumental Track Detection

**Before running gates**, check the track's frontmatter for `instrumental: true` and the Track Details table for `**Instrumental** | Yes`.

**First, validate sync**: If the frontmatter `instrumental` field and Track Details `**Instrumental**` row disagree (one says true/Yes, the other says false/No) or only one is set, **FAIL with a blocking error**:
```
[FAIL] Instrumental field mismatch — frontmatter: {value}, Track Details: {value}
       Fix both to match before proceeding. Gate routing depends on this field.
```
Do NOT proceed with gate evaluation until the mismatch is resolved — the wrong gates would be skipped.

**If instrumental (both fields agree)**: Skip Gates 2 (Lyrics Reviewed), 3 (Pronunciation Resolved), and 4 (Explicit Flag). Mark them as `SKIP — Instrumental track`. Only run Gates 1, 5, and 6.

**Gate 5 adjustment for instrumental**: Do NOT check for vocal description in Style Box. Instead verify the Style Box has genre/instrumentation/mood. Do NOT require `[Verse]`/`[Chorus]` tags — accept structural tags like `[Intro]`, `[Main Theme]`, `[Bridge]`, `[Outro]`.

---

## The Gates

The MCP tool behind this skill reports 8 blocking gates plus 3 advisories (Style Box Descriptor Count, Performance Cues, Generation Settings).

### Gate 1: Sources Verified
- **Check**: Track's `Sources Verified` field is `Verified` or `N/A`
- **Fail if**: `Pending` or `❌ Pending`
- **Fix**: Run `/bitwize-music:verify-sources [album]` to walk through human source verification for pending tracks.
- **Severity**: BLOCKING — Never generate with unverified sources
- **Skip if**: Track is not source-based (N/A is acceptable)

### Gate 2: Lyrics Reviewed
- **Check**: Lyrics Box is populated with actual lyrics (not template placeholders)
- **Check**: No `[TODO]`, `[PLACEHOLDER]`, or template markers in lyrics
- **Fail if**: Empty lyrics box or contains template text
- **Fix**: Run `/bitwize-music:lyric-writer [track]` to write or complete the lyrics.
- **Severity**: BLOCKING

### Gate 3: Pronunciation Resolved
- **Check**: All entries in Pronunciation Notes table have phonetic spellings applied in the Lyrics Box
- **Check**: No unresolved homographs (live, read, lead, wind, tear, bass, etc.)
- **Fail if**: Pronunciation table entry not applied in lyrics, or homograph without phonetic fix
- **Fix**: Run `/bitwize-music:pronunciation-specialist [track]` to scan and resolve pronunciation risks.
- **Severity**: BLOCKING — Suno cannot infer pronunciation from context

### Gate 4: Explicit Flag Set
- **Check**: Track has `Explicit` field set to `Yes` or `No` (not empty/template)
- **Fail if**: Explicit field is missing, empty, or template placeholder
- **Severity**: BLOCKING — the MCP gate fails closed when the flag is unset (#370)

### Gate 5: Style Box Complete
- **Check**: Suno Inputs section has a non-empty Style Box (the `### Style Box` heading in the track template)
- **Check**: Style Box includes vocal description
- **Check**: Section tags present in Lyrics Box (`[Verse]`, `[Chorus]`, etc.)
- **Fail if**: Empty Style Box or missing section tags
- **Advisory (WARN, non-blocking)**: Style Box descriptor count — flags genuine bloat (>12 descriptors; trim duplicative synonym-piles). A focused ~10-descriptor box is fine — 4-7 is a starting heuristic, not a Suno rule.
- **Advisory (WARN, non-blocking)**: Performance Cues — flags ≥2 structure tags with no per-section cues (`[Verse 1 - cold regal]`); bare tags are a common cause of flat, generic output
- **Advisory (WARN, non-blocking)**: Generation Settings — the track's `### Generation Settings` table must record a catalog model (`v6`, `v6-wild`, `v6-mini`, `Custom: <name>`) and **Variety Off**; at any higher Variety Suno rewrites the Style Box, so the descriptor checks above are meaningless. A PASS detail also notes when Max Mode is Off on a track targeting 2:30 or longer (Suno recommends it over two minutes; 2× credits). SKIP when the section is missing — add it from `templates/track.md`.
- **Fix**: Style Box is created by suno-engineer, which is normally auto-invoked by lyric-writer. Run `/bitwize-music:suno-engineer [track]` to create the missing Style Box.
- **Severity**: BLOCKING

### Gate 6: Artist Names Cleared
- **Check**: Style prompt does not contain real artist/band names
- **Reference**: `${CLAUDE_PLUGIN_ROOT}/reference/suno/artist-blocklist.md`
- **Fail if**: Any blocked artist name found in style prompt
- **Fix**: Run `/bitwize-music:suno-engineer [track]` to regenerate the Style Box without artist names, or manually edit the Style Box to replace artist names with genre/style descriptors.
- **Severity**: BLOCKING — Suno filters/blocks artist names

---

## Workflow

### Single Track

1. Call `run_pre_generation_gates(album_slug, track_slug)` — returns all gate results (8 blocking + 3 advisory)
2. Format pass/fail report from MCP response
3. Output verdict: READY or NOT READY

### Full Album

1. Call `run_pre_generation_gates(album_slug)` — returns all gate results (8 blocking + 3 advisory)
2. Format per-track and album-level summary from MCP response
3. Output verdict: ALL READY, PARTIAL (list ready tracks), or NOT READY

---

## Report Format

```markdown
# Pre-Generation Check

**Album**: [name]
**Date**: YYYY-MM-DD

## Track: [XX] - [Title]

| Gate | Status | Details |
|------|--------|---------|
| Sources Verified | PASS | Verified 2025-01-15 |
| Lyrics Reviewed | PASS | 247 words, all sections tagged |

From bitwize-music-studio/claude-ai-music-skills, CC0-1.0.

More from bitwize-music-studio/claude-ai-music-skills