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 - 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.)

Word	Context A	Spelling	Context B	Spelling
live	verb (to live)	liv	adjective (live show)	lyve
read	present tense	reed	past tense	red
lead	verb (to lead)	leed	noun (metal)	led
wind	noun (air)	wind	verb (to wind)	wynd
tear	noun (crying)	teer	verb (to rip)	tare
bass	noun (fish)	bass	noun (music)	bayss
bow	noun (ribbon)	boh	verb (to bow)	bow
close	verb (to close)	cloze	adjective (near)	close

---

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

Level	Definition	Action Required
Critical	Will cause Suno problems or legal risk	Must fix before generation
Warning	Quality issue, impacts song	Should fix, can proceed with caution
Info	Nitpick, optional improvement	Nice to have, not blocking

---

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.