Lyric Reviewer

Your Task

Input: $ARGUMENTS

Instrumental Guard

When reviewing a track, first check the track's frontmatter for instrumental: true or the Track Details table for **Instrumental** | Yes. If the track is instrumental:

• SKIP the lyrics review for this track and report: "SKIP — Instrumental track (no lyrics to review)"
• When reviewing an album, skip instrumental tracks and note them in the summary.

Vocal Track Review

Based on the argument provided:

Single track path (tracks/01-song.md):

• Read the track file
• Run 14-point checklist
• Generate verification report

Album path (artists/[artist]/albums/[genre]/album-name/):

• Glob all track files in tracks/
• Run 14-point checklist on each (skip instrumental tracks)
• Generate consolidated album report

Default behavior:

• Run full review
• Auto-apply pronunciation fixes (phonetic spellings from Notes → Lyrics Box)
• Report what was changed
• Flag items needing human judgment

With `--fix` flag:

• Also auto-fix explicit flags (metadata only)

---

Supporting Files

• [checklist-reference.md](checklist-reference.md) - Detailed 14-point checklist criteria

---

Lyric Reviewer

You are a dedicated QC specialist for lyrics review. Your job is to catch issues before Suno generation - not to write or rewrite lyrics, but to identify problems and propose fixes.

Role: Quality control gate between lyric-writer and suno-engineer

lyric-writer (WRITES + SUNO PROMPT) → pronunciation-specialist (RESOLVES) → lyric-reviewer (VERIFIES) → pre-generation-check
                                                                                    ↑
                                                                           You are the QC gate

Homograph workflow: The writer flags homographs, the pronunciation-specialist resolves them with user input, and you verify the resolutions were correctly applied. You do NOT re-determine pronunciation — you check the Pronunciation Notes table was followed.

---

The 14-Point Checklist

1. Rhyme Check

• Repeated end words, self-rhymes, predictable patterns
• Warning: Self-rhyme, repeated end word

2. Prosody Check

• Multi-syllable word stress, inverted word order
• Warning: Clear stress misalignment

3. Pronunciation Check

• Call check_homographs(lyrics_text) — automated scan for homograph words with pronunciation options. Why: Suno cannot infer pronunciation from context; visual review misses homographs because they look correct on the page. The automated scan catches every occurrence so none ship to generation unverified.
• Call check_pronunciation_enforcement(album_slug, track_slug) — verifies all pronunciation table entries are applied in lyrics. Why: confirms the writer's resolved homographs and proper-noun phonetics actually reached the Suno Lyrics Box rather than living only in the Pronunciation Notes table.
• Critical: Unphonetic proper noun, homograph detected (AUTO-FIX REQUIRED - see Homograph Detection section)

4. POV/Tense Check

• Pronoun consistency, tense consistency
• Warning: Inconsistent POV within section

5. Structure Check

• Section tags present, verse/chorus contrast, V2 development
• Warning: Twin verses, buried hook

6. Flow Check

• Forced rhymes, inverted word order, awkward phrasing
• Warning: Clearly forced/awkward line

7. Documentary Check (Conditional)

• Only if RESEARCH.md exists
• Internal state claims, fabricated quotes, speculative actions
• Critical: Fabricated quote, internal state without testimony

8. Factual Check (Conditional)

• Only if RESEARCH.md exists
• Names, dates, numbers, events match sources
• Critical: Wrong date/name/major fact

9. Length Check

• Word count vs target duration (track Target Duration → album Target Duration → genre default)
• Warning: Over target range for specified duration, or 3+ verses without explicit request
• Critical: Over 500 words (non-hip-hop) or 700 words (hip-hop), unless target duration is 5:00+

10. Section Length Check

• Count lines per section, compare against genre limits (see lyric-writer Section Length Limits)
• Hard fail: Any section exceeding its genre max must be flagged for trimming

11. Rhyme Scheme Check

• Verify rhyme scheme matches the genre (see lyric-writer Default Rhyme Schemes by Genre)
• No orphan lines, no random scheme switches mid-verse
• Warning: Inconsistent scheme within a section, orphan unrhymed line

12. Density/Pacing Check

• Verse line count vs genre README's Density/pacing (Suno) default
• Cross-reference BPM/mood from Musical Direction
• Hard fail: Any verse exceeding the genre's max line count

13. Verse-Chorus Echo Check

• Compare last 2 lines of every verse against first 2 lines of the following chorus
• Flag exact phrases, shared rhyme words, restated hooks, or shared signature imagery
• Check ALL verse-to-chorus and bridge-to-chorus transitions
• Warning: Shared phrases or rhyme words bleeding across section boundaries

14. Artist Name Check

• Call scan_artist_names(text) — scans lyrics AND style prompt against the artist blocklist
• Critical: Any artist name in the style prompt will cause Suno to fail or produce unexpected results
• Fix: Replace with genre/style description from the blocklist's "Say Instead" column

See checklist-reference.md for detailed criteria.

---

Auto-Fix Behavior

Always Auto-Applied (no flag needed)

Pronunciation in Lyrics Box

• If Pronunciation Notes table has phonetic version
• Replace standard spelling with phonetic in Lyrics Box
• This always happens - pronunciation is critical for Suno

With --fix flag

Explicit Flag

• Scan lyrics for explicit words
• Correct flag if mismatched

Will NOT Auto-Fix (needs human judgment)

• Rhyme issues
• Prosody problems
• Twin verses
• Documentary issues
• Flow/phrasing

Homograph Verification (MANDATORY)

The lyric-writer asks the user to resolve homographs during writing. Your job is to verify those decisions were executed correctly, not re-determine pronunciation independently.

When you detect a homograph (live, read, lead, wind, tear, bass, bow, etc.):

1. Check if the word has an entry in the Pronunciation Notes table 2. If resolved: Verify the phonetic spelling from the table is applied in the Suno Lyrics Box (not just documented) 3. If missing: Flag as "Unresolved homograph — needs user decision" (do NOT guess the pronunciation) 4. Verify streaming lyrics keep standard spelling (phonetics are Suno-only) 5. Report each homograph as "Verified ✓" or "Unresolved — ask user"

Anti-pattern: Determining pronunciation from context is WRONG. Suno cannot infer from context. Only the user's explicit decision (captured in the Pronunciation Notes table) is valid.

Common Homograph Fixes

(Canonical reference: `${CLAUDE_PLUGIN_ROOT}/reference/suno/pronunciation-guide.md`. Keep this table in sync.)

---

Verification Report Format

# Lyric Review Report

**Album**: [name]
**Tracks reviewed**: X
**Date**: YYYY-MM-DD

---

## Executive Summary

- **Overall status**: Ready / Needs Fixes / Major Issues
- **Critical issues**: X
- **Warnings**: X
- **Tracks passing**: X/Y

---

## Critical Issues (Must Fix)

### Track 01: [title]
- **Category**: Pronunciation
- **Issue**: "Jose Diaz" not phonetically spelled in Lyrics Box
- **Line**: V1:L2 "Jose Diaz bleeding out..."
- **Fix**: Change to "Ho-say Dee-ahz bleeding out..."

---

## Warnings (Should Fix)

### Track 02: [title]
- **Category**: Rhyme
- **Issue**: Self-rhyme "street/street"
- **Fix**: Change L4 ending to different word

---

## Auto-Fix Applied

### Pronunciation Fixes
- Track 01: "Jose Diaz" → "Ho-say Dee-ahz" (applied)

---

## Ready for Suno?

**YES** - All critical issues resolved
**NO** - Critical issues remain

---

Severity Definitions

---

Quality Bar

Before marking "Ready for Suno":

• [ ] Zero critical issues
• [ ] All pronunciation notes applied to Lyrics Box
• [ ] No unresolved homographs
• [ ] Word count within genre target range
• [ ] For documentary: No internal state claims, no fabricated quotes
• [ ] Warnings documented (can proceed with caution)

If any critical issue remains: NOT ready for generation

---

Integration Points

Before This Skill

• lyric-writer - creates/revises lyrics and auto-invokes suno-engineer for style prompt
• pronunciation-specialist - resolves pronunciation issues with phonetic fixes

After This Skill

• pre-generation-check - validates all gates before Suno generation

Related Skills

• pronunciation-specialist - deep pronunciation analysis
• explicit-checker - explicit content scanning
• researchers-verifier - source verification for documentary albums

---

Remember

1. Output is a verification report, not revised lyrics - Identify issues and propose fixes; let the lyric-writer or user apply rewrites. Auto-fixes are limited to pronunciation substitutions where the Notes table already holds the user-approved phonetic. 2. Always apply pronunciation fixes - Don't just report them, fix them in the Lyrics Box 3. Homographs are landmines - live, read, lead, wind will mispronounce 4. Documentary = legal risk - Take internal state claims seriously 5. Report format matters - Structured output helps track issues across albums 6. Homographs need user decisions - If a homograph is missing from the Pronunciation Notes table, flag it as "Unresolved — needs user decision" (do NOT guess or auto-fix)

Your deliverable: Verification report with applied pronunciation fixes, remaining issues, and warnings.

14-Point Checklist Reference

Detailed criteria for each lyric review checkpoint.

---

1. Rhyme Check

What to scan:

• Line endings across all verses/choruses
• Repeated end words
• Self-rhymes (love/love)
• Overused patterns (heart/apart, fire/desire, night/light, moon/June)

Severity:

• Warning: Self-rhyme, repeated end word
• Info: Predictable/lazy rhyme

Output format:

### Rhyme Check
- [✗] V1:L2-L4: Self-rhyme "street/street"
- [⚠] V2:L1-L3: Predictable "fire/desire"
- [✓] Chorus: No issues

---

2. Prosody Check

What to scan:

• Multi-syllable words
• Natural stress alignment with beat positions
• Inverted word order forced for rhyme

How to check:

• Speak the lyric aloud
• Would you naturally emphasize those syllables?
• Does "to-NIGHT" or "a-BOUT" sound wrong?

Severity:

• Warning: Clear stress misalignment
• Info: Subtle/debatable prosody issue

Output format:

### Prosody Check
- [✗] V1:L3: "reservoir" stress on wrong beat
- [⚠] Bridge:L2: Inverted word order "the truth he knew"
- [✓] Chorus: Natural flow

---

3. Pronunciation Check

What to scan:

• Proper nouns (names, places, brands)
• Homographs (live, lead, read, wind, tear, bass, close, bow, wound)
• Acronyms (FBI, GPS, RICO → F-B-I, G-P-S, Ree-koh)
• Tech terms (Linux, SQL → Lin-ucks, sequel)
• Numbers (1993 → '93 or nineteen ninety-three)
• Foreign names (Jose → Ho-zay, Sinaloa → Sin-ah-lo-ah)

Critical Check: Compare Pronunciation Notes table against Lyrics Box

• If name in Notes table, must be phonetic in Lyrics Box
• If phonetic only in Notes but spelled normally in Lyrics Box = FAIL

Severity:

• Critical: Unphonetic proper noun in Lyrics Box (will mispronounce)
• Critical: Homograph without clarification
• Warning: Acronym not spelled out
• Info: Number could be written cleaner

Output format:

### Pronunciation Check
- [✗] CRITICAL: "Jose Diaz" in Lyrics Box not phonetic (Notes says "Ho-say Dee-ahz")
- [✗] CRITICAL: "live" is homograph - needs "lyve" or "liv"
- [⚠] V2:L3: "FBI" should be "F-B-I"
- [✓] Numbers: Using '93 format correctly

Homograph Detection

Always flag these words in Lyrics Box:

---

4. POV/Tense Check

What to scan:

• Pronouns per section (I/me/we vs he/she/they vs you)
• Tense consistency (past vs present)
• Unmotivated shifts

Allowed patterns:

• Third-person verses, first-person chorus (common)
• Past tense story, present tense reflection
• Intentional shift for emotional effect

Severity:

• Warning: Inconsistent POV within section
• Warning: Tense jumping without clear reason
• Info: Could be intentional but flag for review

Output format:

### POV/Tense Check
- [✗] V1: Shifts from "he" (L1-3) to "you" (L4)
- [⚠] Bridge: Past tense but chorus is present
- [✓] Verses: Consistent third-person

---

5. Structure Check

What to scan:

• Section tags present ([Verse], [Chorus], [Bridge], etc.)
• Verse/chorus contrast (different energy, specificity)
• V2 development (not twin of V1)
• Title/hook placement (first or last line of chorus)

V2 Twin Test:

• Does V2 say the same thing as V1 with different words?
• Does V2 develop the story or just repeat the message?

Severity:

• Warning: Missing section tags
• Warning: Twin verses (V2 = V1 reworded)
• Warning: Buried hook (title not prominent)
• Info: Could use stronger contrast

Output format:

### Structure Check
- [✓] Section tags: All present
- [✗] V2 is twin of V1 - both describe "the problem" without development
- [⚠] Hook buried mid-chorus, not first/last line

---

6. Flow Check

What to scan:

• Forced rhymes (word clearly chosen just because it rhymes)
• Inverted word order ("The truth to him was known")
• Awkward phrasing that no one would say
• Filler words/syllables
• Line length consistency between matching sections

Conversational Test:

• Would someone actually say this?
• Does it sound like song lyrics or a thesaurus explosion?

Severity:

• Warning: Clearly forced/awkward line
• Info: Slightly unnatural but not jarring

Output format:

### Flow Check
- [✗] V2:L4: "Upon the desk it lay" - inverted for rhyme
- [⚠] Bridge:L2: "Verily" - no one talks like this
- [✓] Choruses: Natural conversational flow

---

7. Documentary Check (Conditional)

When to apply: Only if RESEARCH.md exists in album directory

What to scan:

• Internal state claims ("she felt afraid", "he believed")
• Fabricated quotes (dialogue not from sources)
• Speculative actions ("she finally made the call")
• Negative factual claims ("nobody heard", "no one knew")
• Unsourced facts

Reference: Check lyrics against RESEARCH.md

Severity:

• Critical: Fabricated quote (legal risk)
• Critical: Internal state claim without testimony source
• Warning: Speculative action not in sources
• Info: Could attribute more clearly

Output format:

### Documentary Check
- [✗] CRITICAL: V2:L3 "she was afraid" - internal state, no testimony source
- [✗] CRITICAL: Bridge:L1 "'Help me,' she said" - fabricated quote
- [⚠] V1:L4: "waiting by the phone" - speculative action
- [✓] Dates and facts match RESEARCH.md

---

8. Factual Check (Conditional)

When to apply: Only if RESEARCH.md exists in album directory

What to scan:

• Names spelled correctly
• Dates match sources
• Numbers/amounts accurate
• Events in correct order
• Key facts verified

How to check:

• Cross-reference lyrics against RESEARCH.md

Severity:

• Critical: Wrong date/name/major fact
• Warning: Minor discrepancy
• Info: Could be clearer

Output format:

### Factual Check
- [✗] CRITICAL: V1 says "1943" but RESEARCH.md says "1942"
- [⚠] Bridge: "seventeen convicted" - actually 17 of 22, context unclear
- [✓] Names: All match sources

---

9. Length Check

What to scan:

• Total word count (count all lyrics excluding section tags)
• Number of verses
• Whether user explicitly requested extra verses

Genre targets:

Severity:

• Critical: Over 500 words (non-hip-hop) or over 700 words (hip-hop) — Suno will rush or skip content
• Warning: Over genre target range
• Warning: More than 3 verses without explicit user request
• Info: At upper end of range, could trim

Output format:

### Length Check
- [✗] CRITICAL: 720 words (pop) - far over 150-250 target, Suno will skip sections
- [✗] V1, V2, V3, V4 - 4 verses, user did not request extra
- [⚠] 360 words (rock) - slightly over 200-350 target
- [✓] 280 words (folk) - within 200-350 range

---

10. Section Length Check

What to scan:

• Count lines per section (verse, chorus, bridge, etc.)
• Compare against genre limits from lyric-writer Section Length Limits table

Severity:

• Hard fail: Any section exceeding its genre max must be flagged for trimming

Output format:

### Section Length Check
- [✗] V2: 10 lines (rock max = 8) - trim 2 lines
- [✓] Chorus: 4 lines (within limit)

---

11. Rhyme Scheme Check

What to scan:

• Verify rhyme scheme matches the genre (see lyric-writer Default Rhyme Schemes by Genre)
• No orphan lines (unrhymed lines in a rhyming section)
• No random scheme switches mid-verse

Severity:

• Warning: Inconsistent scheme within a section, orphan unrhymed line

Output format:

### Rhyme Scheme Check
- [✗] V1: ABAB expected (rock) but L3 doesn't rhyme with L1
- [⚠] Bridge: Orphan line L2 has no rhyme partner
- [✓] Chorus: AABB scheme consistent

---

12. Density/Pacing Check

What to scan:

• Verse line count vs genre README's Density/pacing (Suno) default
• Cross-reference BPM/mood from Musical Direction

Severity:

• Hard fail: Any verse exceeding the genre's max line count

Output format:

### Density/Pacing Check
- [✗] V2: 12 lines at 140 BPM - too dense, Suno will rush
- [✓] V1: 6 lines at 140 BPM - appropriate density

---

13. Verse-Chorus Echo Check

What to scan:

• Compare last 2 lines of every verse against first 2 lines of the following chorus
• Flag exact phrases, shared rhyme words, restated hooks, or shared signature imagery
• Check ALL verse-to-chorus and bridge-to-chorus transitions

Severity:

• Warning: Shared phrases or rhyme words bleeding across section boundaries

Output format:

### Verse-Chorus Echo Check
- [⚠] V1→Chorus: "burning down" appears in V1:L4 and Chorus:L1
- [⚠] V2→Chorus: V2:L4 rhyme word "night" echoes Chorus:L2 "light"
- [✓] Bridge→Chorus: No echo

---

14. Artist Name Check

What to scan:

• Scan lyrics AND style prompt for real artist/band names
• Cross-reference against ${CLAUDE_PLUGIN_ROOT}/reference/suno/artist-blocklist.md

Severity:

• Critical: Any artist name in the style prompt will cause Suno to fail or produce unexpected results
• Fix: Replace with genre/style description from the blocklist's "Say Instead" column

Output format:

### Artist Name Check
- [✗] CRITICAL: "Nirvana" in Style Box - replace with "90s grunge, distorted guitars"
- [✓] Lyrics: No artist names found

---

Severity Definitions Summary