/pre-generation-check

name: pre-generation-check
description: Validates all pre-generation gates before sending tracks to Suno. Checks sources verified, lyrics reviewed, pronunciation resolved, explicit flag set, style prompt complete, and artist names cleared. Use before generating tracks on Suno or when the user says "pre-gen check" or "ready to generate".
argument-hint: <album-name or track-path>
model: haiku
prerequisites:
  - lyric-writer
  - lyric-reviewer
  - pronunciation-specialist
allowed-tools:
  - Read
  - Glob
  - Grep
  - bitwize-music-mcp

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/block