# Phase 1: Foundation - Research

**Researched:** 2026-04-10
**Domain:** Project skeleton — CLAUDE.md, reference file structure, Suno V5.5 specs, linguistic rule stubs, folder conventions
**Confidence:** HIGH

## Summary

Phase 1 is pure infrastructure: creating the project skeleton that every future phase depends on. There is no code, no runtime — only markdown files organized into a precise hierarchy. The research covers four domains: (1) CLAUDE.md structure and behavioral rules, (2) Suno V5.5 Custom Mode technical specifications, (3) French and English linguistic rule foundations, and (4) reference file organization patterns.

The most critical finding is a **character limit discrepancy** in the earlier STACK.md research. The Suno API documentation confirms that V5/V5.5 models support **1,000 characters for style prompts** and **5,000 characters for lyrics** (up from 200/3,000 in V4). Earlier research cited the V4 limits. The reference file must document the V5.5 limits with a note that practical best practice is to stay under ~3,000 chars for lyrics (beyond which Suno rushes or skips sections) and to front-load style prompts (earlier tags carry more weight).

The Persona feature (now called "Voices" in V5.5) is a voice persistence feature, not a style persistence feature. Each artist would have one Voice profile in Suno that captures their vocal timbral qualities. This is worth noting in the Suno reference but does not need detailed documentation per the user's decision.

**Primary recommendation:** Build the skeleton file-by-file following the locked decisions exactly. The Suno format reference (`reference/suno/format.md`) is the single most complex deliverable and should be informed by the verified technical specs below. CLAUDE.md should be concise and action-oriented following established best practices (shallow heading hierarchy, rationale for every prohibition, code blocks for all paths/commands).

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions

#### CLAUDE.md Behavioral Rules
- **Language:** All interactions in French by default
- **Reference authority:** Reference files always win over Claude's training data — no substitutions
- **Workflow rules:** CLAUDE.md includes behavioral rules for artist creation, track production, and verification workflows (not just project-level rules)
- **Quality gates:** Strict — Claude must verify Suno constraints and linguistic quality before outputting final content. Never skip verification
- **Verification bundling:** Every lyrics output automatically includes syllable counts, rhyme analysis, and Suno constraint checks inline — not a separate step
- **Production brief format:** CLAUDE.md specifies exact sections and order for production briefs (style prompt, lyrics, verification report, notes)
- **Lore handling:** Artist lore informs tone and themes as guidance but doesn't need explicit references in every track
- **File naming:** CLAUDE.md defines naming conventions for all project outputs (artists, tracks, briefs)
- **Bilingual policy:** One language per track, no mixing. Language is chosen at track creation
- **Creativity:** Bible is law — Claude strictly follows the artist bible for genre, themes, emotions with no deviation
- **Persona:** Creative collaborator — enthusiastic, suggests ideas, engages with the creative vision
- **Auto-save:** Claude writes files and user reviews after — no confirmation prompt before saving
- **Auto-log discography:** Every finalized track is automatically added to the artist's discography.md
- **Explicit don'ts:** Include a clear list of prohibited behaviors, derived from the established rules
- **Update policy:** CLAUDE.md defines how to handle updates to external tools like Suno (reference files are updated, CLAUDE.md stays stable)
- **Feedback handling:** Revise lyrics in place based on feedback, preserving the rest
- **Creative reasoning:** Always provide brief reasoning alongside creative output explaining choices
- **Next steps:** Always suggest what to do next after completing a workflow step
- **Edge cases:** Cover non-standard track types (intros, interludes, spoken word, freestyle) with adapted verification criteria
- **Non-standard verification:** Verification still runs for non-standard formats but criteria adapt (e.g., flow/cadence for spoken word instead of strict rhyme)
- **Verse progression:** Each verse must advance the narrative or explore a new angle — no repetitive content across verses
- **Chorus rules:** Chorus must be memorable, concise, and capture the track's emotional core
- **Track finality:** Once saved, a track is part of the discography — no draft state
- **Explicit content:** No restrictions — Claude generates content matching the artist's style. Explicit language allowed when it fits genre and identity
- **Suno details:** Technical Suno constraints live in reference files, CLAUDE.md just instructs to check them

#### Suno Format Specs
- **Depth:** Full reference guide — constraints, examples, best practices, tips. Research from internet
- **Version:** Suno V5.5 (latest)
- **Scope:** Custom Mode only
- **Tag library:** Include a curated list of style tags, genres, vocal descriptors that produce good results
- **Style prompt formula:** Document the recommended formula/ordering from Suno's official guidance (research from internet)
- **Spec focus:** Just the spec — no anecdotal quirks or limitations section
- **Tag organization:** Claude's discretion on how to organize the tag library for maximum usability
- **Section tag mapping:** List every valid Suno section tag with its purpose and mapping to standard song structure
- **Personas:** Note that the feature exists (each artist has one Persona voice) — brief mention, not detailed documentation
- **Sweet spots:** Document recommended style prompt length ranges and their effect on output quality
- **Paste template:** Include a visual example of the final copy-paste format for Custom Mode
- **Language handling:** Document how Suno detects/handles language and what prompt additions ensure correct pronunciation
- **Vocal metatags:** Compile a complete list of working vocal delivery metatags ([Whispered], [Raspy], [Belted], etc.)
- **Tempo guidance:** Document how BPM/tempo can be influenced through style prompts and genre selection
- **Duration control:** Document how track length is influenced by lyrics/sections and any Suno limits

#### Reference Organization
- **Structure:** By domain — `reference/suno/`, `reference/linguistic/`, `reference/templates/`
- **Linguistic files:** Split by topic per language — `reference/linguistic/french/syllables.md`, `french/rhymes.md`, `french/pronunciation.md`
- **Suno reference:** One comprehensive file — `reference/suno/format.md` contains everything
- **File format:** All reference files follow a consistent template: Purpose, Rules, Examples, Notes
- **Song templates:** Live in `reference/templates/`
- **Index:** `reference/README.md` listing every file with a one-line description
- **Artists README:** `artists/README.md` includes both folder structure conventions and a summary of the artist bible format
- **Output location:** Tracks live only in `artists/[name]/tracks/` — no separate output folder
- **Structure doc:** Top-level `STRUCTURE.md` mapping out the entire folder hierarchy
- **Metadata:** Each reference file includes YAML frontmatter or header with last-updated date and source
- **Glossary:** Music terms glossary lives in `reference/glossary.md` (separate from CLAUDE.md), using English terms universally

#### Linguistic Rule Stubs
- **French depth:** Headers + core rules — include e muet rules, basic rhyme types, common dierese cases so Phase 5 extends rather than starts from scratch
- **English depth:** Headers + core rules — include basic syllable/rhyme rules (stress patterns, rhyme types)
- **French rhyme scale:** Define the full quality classification now: pauvre (1), suffisante (2), riche (3+), richissime (4+) with definitions and examples
- **French pronunciation pitfalls:** Include known French pronunciation issues affecting AI music generation (silent letters, nasal vowels)
- **E muet rules:** Include specific rules for when final 'e' counts as a syllable vs silent, with examples
- **Phonetic notation:** Use IPA (International Phonetic Alphabet) for all pronunciation references
- **English rhyme types:** Define all types with examples: perfect, slant, near, and eye rhymes
- **Genre adjustments:** Note how linguistic rules flex by genre (rap allows more slant rhymes, pop requires stricter counts)
- **French quality thresholds:** Section-dependent — chorus requires riche (3+), verses allow suffisante (2+), bridge is flexible
- **English quality:** Near/slant rhymes allowed alongside perfect rhymes (modern songwriting standard)
- **Syllable targets:** Genre-dependent ranges (rap = more syllables/line, ballad = fewer)
- **Rhyme schemes:** Document common patterns (AABB, ABAB, ABCB) with genre/section guidance
- **Borrowed words:** Document rules for foreign words — apply French pronunciation for syllable counting in French lyrics
- **Poetic license:** No exceptions — all lines must meet quality thresholds. Rules are rules
- **Internal rhymes:** Document and encourage internal rhymes as a richness indicator
- **Full sonic toolkit:** Document assonance, alliteration, and consonance as additional quality indicators alongside rhyme

### Claude's Discretion
- Tag library organization (genre family hierarchy vs flat list vs categorized)
- Exact wording of CLAUDE.md don'ts section (derived from the rules above)

### Deferred Ideas (OUT OF SCOPE)
None — discussion stayed within phase scope
</user_constraints>

## Standard Stack

This phase produces no code — only markdown files. The "stack" is the file organization itself.

### Core
| Component | Spec | Purpose | Why Standard |
|-----------|------|---------|--------------|
| CLAUDE.md | Root-level, <200 lines | Project behavioral instructions for Claude | Official Claude Code configuration file. Read at session start. |
| Reference files | Markdown with metadata headers | Authoritative knowledge that overrides Claude's training | Markdown is natively readable by Claude, versionable, human-editable |
| STRUCTURE.md | Root-level | Project folder hierarchy map | Single source of truth for where everything lives |

### Supporting
| Component | Spec | Purpose | When to Use |
|-----------|------|---------|-------------|
| `reference/README.md` | Index file | Quick-reference listing all reference files | When navigating the reference directory |
| `artists/README.md` | Convention doc | Per-artist folder structure and bible format summary | When creating a new artist |
| `reference/glossary.md` | Term definitions | English music terminology used universally | When terms need clarification across languages |

## Architecture Patterns

### Recommended Project Structure (Phase 1 Output)

```
AI_ARTISTE/
|
+-- CLAUDE.md                           # Behavioral instructions for Claude
+-- STRUCTURE.md                        # Folder hierarchy map
|
+-- reference/
|   +-- README.md                       # Index of all reference files
|   +-- glossary.md                     # Music terms glossary (English universally)
|   |
|   +-- suno/
|   |   +-- format.md                   # Comprehensive Suno V5.5 Custom Mode reference
|   |
|   +-- linguistic/
|   |   +-- french/
|   |   |   +-- syllables.md            # French syllable counting rules
|   |   |   +-- rhymes.md               # French rhyme classification
|   |   |   +-- pronunciation.md        # French pronunciation for AI generation
|   |   +-- english/
|   |       +-- syllables.md            # English syllable counting rules
|   |       +-- rhymes.md               # English rhyme classification
|   |
|   +-- templates/                      # (Empty for Phase 1 — populated in Phase 3)
|       +-- .gitkeep
|
+-- artists/
|   +-- README.md                       # Folder conventions + artist bible format summary
|
+-- base/                               # Legacy reference (existing files, untouched)
    +-- project.md
    +-- production.md
```

### Pattern 1: Reference File Template

Every reference file follows a consistent structure per the locked decision.

```markdown
---
last-updated: 2026-04-10
source: [origin of the information]
---

# [File Title]

## Purpose

[1-2 sentences: what this file is for, when to consult it]

## Rules

[The actual rules, numbered or bulleted]

## Examples

[Concrete examples illustrating each rule]

## Notes

[Edge cases, caveats, cross-references to other files]
```

### Pattern 2: CLAUDE.md Structure

Based on best practices research, CLAUDE.md should follow these formatting principles:

- **Shallow heading hierarchy:** h1 for title, h2 for sections, h3 for subsections. No h4.
- **Rationale for every prohibition:** "Never mix languages in a track — Suno drifts between accents at section boundaries" not just "Never mix languages"
- **Code blocks for all paths and commands:** File paths, naming patterns, and references in backticks
- **Concise and action-oriented:** Every line is an instruction Claude can act on. No prose explanation of the project philosophy.
- **Progressive disclosure:** CLAUDE.md points to reference files for details, does not duplicate them
- **Emphasis sparingly:** Use IMPORTANT/MUST only for rules where violation causes system failure

**Recommended CLAUDE.md sections (in order):**
1. `# AI Artiste` — one-line project description
2. `## Langue` — French by default instruction
3. `## Principes` — Core rules (reference authority, bible is law, auto-save)
4. `## Workflows` — Behavioral rules per workflow type (artist creation, track production, verification)
5. `## Format de Production` — Exact sections/order for production briefs
6. `## Conventions de Nommage` — File naming rules
7. `## Verification` — Quality gates, bundled verification, adapted criteria for non-standard tracks
8. `## Interdictions` — Explicit don'ts list with rationale
9. `## Mises a Jour` — Update policy for external tools

### Anti-Patterns to Avoid

- **Duplicating reference content in CLAUDE.md:** CLAUDE.md says "check `reference/suno/format.md`", it does NOT list Suno constraints itself. This prevents drift between CLAUDE.md and reference files.
- **Overloading CLAUDE.md:** If it exceeds ~200 lines, Claude starts ignoring rules. Ruthlessly prune.
- **Vague prohibitions without rationale:** Every "never" needs a "because" — this helps Claude generalize to similar situations.
- **Creative section names:** Use standard names (`## Conventions`, `## Verification`) not creative ones (`## The Golden Rules`, `## Quality Compass`).

## Suno V5.5 Technical Specifications (Verified)

### Character Limits by Model Version

| Field | V4 | V4.5 / V5 / V5.5 | Source |
|-------|----|--------------------|--------|
| **Style Prompt** | 200 chars | **1,000 chars** | Suno API docs (HIGH) |
| **Lyrics** | 3,000 chars | **5,000 chars** | Suno API docs (HIGH) |
| **Title** | 80 chars | **100 chars** | Suno API docs (HIGH) |

**IMPORTANT:** Earlier project research (STACK.md) cited V4 limits (200/3000/80). The reference file MUST use the V5.5 limits. Practical best practices still recommend conservative usage:

| Field | Hard Limit | Sweet Spot | Why |
|-------|-----------|------------|-----|
| Style Prompt | 1,000 chars | 200-500 chars | Earlier tags carry more weight; beyond 500 chars, later tags have diminishing impact |
| Lyrics | 5,000 chars | 2,000-3,000 chars | Beyond ~3,000 chars Suno rushes, skips sections, or produces shorter output |
| Title | 100 chars | 30-50 chars | Display purposes only, does not affect music |

**Confidence: HIGH** — Verified via Suno API documentation (docs.sunoapi.org) which explicitly lists V5 and V5_5 model limits.

### Style Prompt Formula

Suno weighs earlier tags more heavily. Recommended ordering (5-part formula):

1. **Genre + Subgenre** (1-2 tags) — the foundation, always first
2. **Mood / Energy** (1-2 descriptors) — emotional direction
3. **Vocal Direction** (1-2 tags) — gender, tone, delivery style
4. **Instrumentation** (2-3 instruments) — key sounds
5. **Production + Tempo** (1-2 tags) — mix aesthetic, BPM

**Optimal tag count:** 8-15 comma-separated tags. Fewer than 5 = too generic. More than 20 = contradictions and dilution.

**Format:** Comma-separated tags only. Full sentences waste characters. Use BPM numbers ("128 BPM") not descriptors ("medium tempo").

**Negative prompting:** Suno does not support "don't do X" directly. Instead, be specific about what you want, leaving no room for what you don't want.

**Confidence: HIGH** — Cross-verified across HookGenius guide, Blake Crosley reference, and Suno prompt guide 2026.

### Section/Structure Metatags (Complete Verified List)

**Primary Structure:**
| Tag | Purpose | Song Structure Mapping |
|-----|---------|----------------------|
| `[Intro]` | Opening section, often instrumental | Sets atmosphere before vocals |
| `[Verse]` / `[Verse 1]`, `[Verse 2]` | Main narrative sections | Storytelling, advances the narrative |
| `[Pre-Chorus]` | Tension build before hook | Transitional, raises energy |
| `[Chorus]` | Main hook, repeated | Emotional peak, memorable |
| `[Post-Chorus]` | Extension after chorus | Sustains energy, adds hooks |
| `[Bridge]` | Contrasting section | Emotional/stylistic pivot |
| `[Outro]` | Closing section | Resolution, fade |
| `[End]` | Abrupt ending | Hard stop signal |

**Special Structure:**
| Tag | Purpose |
|-----|---------|
| `[Instrumental]` | No vocals, music only |
| `[Interlude]` | Short musical break between sections |
| `[Break]` | Stripped-down moment, rhythm/melody pauses |
| `[Drop]` | EDM-style drop after build |
| `[Build]` / `[Build-Up]` | Rising intensity leading to climax |
| `[Hook]` | Short catchy repeated phrase |
| `[Refrain]` | Repeated line, shorter than chorus |
| `[Solo]` / `[Guitar Solo]` | Instrumental solo section |
| `[Breakdown]` | Deconstructed beat/stripped arrangement |

**Numbering:** Use `[Verse 1]`, `[Verse 2]` to signal melody variation. Identical `[Chorus]` tags encourage melodic repetition across choruses.

**Confidence: HIGH** — Cross-verified across HookGenius, Musci.io, and Blake Crosley reference.

### Vocal Delivery Metatags (Complete Verified List)

**Volume & Intensity:**
`[Whispered]`, `[Soft]`, `[Gentle]`, `[Quiet]`, `[Spoken]`, `[Spoken Word]`, `[Powerful]`, `[Belted]`, `[Shouted]`, `[Screamed]`, `[Growled]`, `[Intense]`

**Vocal Style:**
`[Falsetto]`, `[Head Voice]`, `[Chest Voice]`, `[Breathy]`, `[Raspy]`, `[Smooth]`, `[Soulful]`, `[Operatic]`, `[Nasal]`, `[Airy]`, `[Crooning]`

**Vocal Techniques:**
`[Harmonies]`, `[Ad-libs]`, `[Vocal Run]`, `[Melisma]`, `[Vibrato]`, `[Staccato]`, `[Legato]`, `[Call and Response]`, `[Chant]`, `[Choir]`, `[A cappella]`, `[Humming]`, `[Backing Vocals]`, `[Scat]`

**Rap & Hip-Hop Delivery:**
`[Rapped]`, `[Fast Rap]`, `[Slow Flow]`, `[Melodic Rap]`, `[Trap Flow]`, `[Boom Bap Flow]`, `[Mumble Rap]`, `[Double Time]`

**Vocal Effects:**
`[Reverb]`, `[Delay]`, `[AutoTune]`, `[No AutoTune]`, `[Distorted Vocals]`, `[Filtered Vocals]`, `[Vocoder]`, `[Telephone Effect]`

**Vocal Emotion (inline):**
`[Vulnerable]`, `[Powerful]`, `[Soft]`, `[Aggressive]`, `[Melancholic]`, `[Joyful]`, `[Sultry]`, `[Defiant]`

**Dynamics (V5+):**
`[Fade In]`, `[Fade Out]`, `[Swell]`, `[Crescendo]`, `[Decrescendo]`

**Negative (V5+):**
`[no vocals]`, `[no autotune]`, `[no reverb]`, `[no falsetto]`, `[no choir]`, `[no drums]`, `[no synths]`, `[no distortion]`, `[no electronic elements]`

**Placement rules:** Place delivery tags on their own line before the lyrics they affect. One primary delivery cue per section works best. Stacking multiple cues (e.g., `[Whispered, emotional, crescendo]`) reduces clarity.

**Confidence: HIGH** — Compiled from HookGenius, Musci.io, Blake Crosley, and OpenMusicPrompt. Cross-verified across 4+ sources.

### Persona / Voices Feature

- **V5.5 renamed Personas to Voices.** All previous Personas are preserved in the new Voices tab.
- **What it does:** Captures vocal timbral qualities (timbre, resonance, texture) from a reference audio. When generating new songs with a Voice, Suno applies those vocal characteristics.
- **How to create:** Upload audio or record live. Suno isolates the vocal via stem separation. Anti-deepfake verification requires speaking a random phrase.
- **Access:** Pro ($10/mo) and Premier ($30/mo) only.
- **For this project:** Each artist gets one Suno Voice profile that ensures vocal consistency across all tracks. The Voice captures "who sings" while the style prompt captures "how the song sounds."
- **Audio Influence slider:** Controls how strongly the Voice profile affects output. Higher = more faithful to the original voice.
- **Integration with metatags:** Works alongside delivery tags like `[Whispered]` and `[Belted]`.

**Confidence: HIGH** — Verified via Suno official help center and blog.

### Language Handling

- **Detection:** Suno infers language from the lyrics text. No explicit language selector exists.
- **Best practice for French:** Add "All lyrics in French" or "Sung in French" to the style prompt. This prevents mid-track language drift.
- **Style prompt language:** The style prompt itself is always in English, regardless of lyrics language.
- **Mixed language:** One language per section is recommended. Do not mix languages within a single verse or Suno may drift between accents.
- **Pronunciation:** Suno predicts pronunciation from spelling patterns, not phonetic rules. For mispronounced French words, spell them phonetically (how they sound, not standard spelling). Keep lines moderate length — syllable-dense lines (12+) cause slurring at fast tempos.
- **Supported languages:** French is among the best-supported non-English languages (alongside Spanish, Portuguese, Japanese, Korean, Mandarin).

**Confidence: MEDIUM** — Compiled from community guides (HookGenius, Jack Righteous). No official Suno documentation on language handling exists.

### Duration Control

| Model Version | Max Generation | Notes |
|---------------|---------------|-------|
| V3 | 2 minutes | |
| V3.5 / V4 | 4 minutes | |
| V4.5 / V5 | 8 minutes | |
| V5.5 | 4 minutes per generation | Can chain via Extend feature |

- **Lyrics affect duration:** More lyrics = denser vocal content. Very long lyrics risk rushed delivery.
- **Fewer lyrics with `[Instrumental]` breaks** = breathing room, natural feel.
- **Extend feature:** Adds ~30-60 seconds per extension. Can chain to reach 12+ minutes on Premier plan.
- **Practical sweet spot:** 2-4 minutes for a single generation is the quality sweet spot.

**Confidence: MEDIUM** — Official Suno help center confirms V4.5/V5 = 8 min. V5.5 = 4 min per generation is from HookGenius guide, needs validation.

### BPM / Tempo Guidance

- Use explicit BPM notation: "128 BPM" not "medium tempo" or "upbeat"
- BPM is approximate guidance, not a metronome lock
- Genre-specific ranges for reference:
  - Lo-fi / Chill: 60-85 BPM
  - Ballad: 60-80 BPM
  - R&B / Neo-Soul: 70-100 BPM
  - Pop: 100-130 BPM
  - Rock: 110-140 BPM
  - House / Dance: 120-130 BPM
  - Techno: 125-150 BPM
  - Drum and Bass: 160-180 BPM
  - Trap / Hip-Hop: 130-170 BPM (half-time feel)

**Confidence: MEDIUM** — From HookGenius prompt guide. BPM ranges are standard music industry knowledge.

### Copy-Paste Template for Custom Mode

The reference file should include this visual example showing the exact format a user pastes into Suno:

```
┌─────────────────────────────────────────────┐
│ SUNO CUSTOM MODE                            │
├─────────────────────────────────────────────┤
│ Title:                                      │
│ ┌─────────────────────────────────────────┐ │
│ │ Track Title Here                        │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ Style of Music: (max 1000 chars)            │
│ ┌─────────────────────────────────────────┐ │
│ │ genre, subgenre, mood, vocal direction, │ │
│ │ instruments, production, BPM            │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ Lyrics: (max 5000 chars)                    │
│ ┌─────────────────────────────────────────┐ │
│ │ [Intro]                                 │ │
│ │ (instrumental)                          │ │
│ │                                         │ │
│ │ [Verse 1]                               │ │
│ │ First line of lyrics                    │ │
│ │ Second line of lyrics                   │ │
│ │ ...                                     │ │
│ │                                         │ │
│ │ [Chorus]                                │ │
│ │ Hook line here                          │ │
│ │ ...                                     │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ [v5.5 ▼]  [Voice: optional]  [Create ♪]    │
└─────────────────────────────────────────────┘
```

## French Linguistic Rules (Foundation for Stubs)

### Syllable Counting (E Muet Rules)

The e muet (mute e / silent e) is the primary source of syllable counting errors in French verse. Rules:

**When e muet IS counted as a syllable:**
- Before a consonant: "un**e** chanson" = e counts (un-e chan-son = 4 syllables)
- Before an aspirated h: "un**e** haine" = e counts

**When e muet is NOT counted (elided):**
- Before a vowel: "bell**e** amie" = e is silent (bel-la-mie = 3 syllables)
- Before a non-aspirated h: "bell**e** histoire" = e is silent
- At the end of a line: the final e is always hypermetrical (outside the count)
- Verb endings "-ent" (3rd person plural): "ils chant**ent**" = -ent is silent

**Example with IPA:**
- "La rime est une esclave" → La-ri-m(e)-es-tu-nes-cla-ve
  - First "e" in "rime" elides before "est" (vowel)
  - "e" in "une" elides before "esclave" (vowel)
  - Final "e" in "esclave" at line end = not counted
  - Count: 7 syllables

### Dierese and Synerese

**Dierese (diérèse):** Splitting a vowel cluster into two separate syllables. "Passion" = pa-ssi-**on** (3 syllables, not 2). "Lion" = li-**on** (2 syllables). "Violet" = vi-o-let (3 syllables). Applies to words of Latin origin where the vowels were historically separate.

**Synerese (synérèse):** Merging two adjacent vowels into one syllable. "Hier" = hier (1 syllable). "Pied" = pied (1 syllable). The default in modern spoken French.

**Rule of thumb for verse:** Refer to Latin origin or standard prosody tables. In this project, the reference file should list common dierese cases to avoid ambiguity.

### French Rhyme Classification

| Category | Shared Phonemes | Definition | Examples |
|----------|----------------|------------|----------|
| **Pauvre** (poor) | 1 | Only the stressed vowel matches | ami /a.mi/ — parti /paʁ.ti/ (shared: /i/) |
| **Suffisante** (sufficient) | 2 | Two phonemes match including a vowel | chanson /ʃɑ̃.sɔ̃/ — maison /mɛ.zɔ̃/ (shared: /ɔ̃/) + consonant context |
| **Riche** (rich) | 3+ | Three or more shared phonemes | lumière /ly.mjɛʁ/ — poussière /pu.sjɛʁ/ (shared: /jɛʁ/) |
| **Richissime** (very rich) | 4+ | Four or more shared phonemes | tendresse /tɑ̃.dʁɛs/ — tristesse /tʁis.tɛs/ (shared: /dʁɛs/ or more) |

**Counting method:** Count shared phonemes from the last stressed vowel to the end of the word. Phonemes, not letters — analysis must be phonetic (IPA-based), not orthographic.

**Quality thresholds (per user decision):**
- Chorus: requires riche (3+)
- Verses: allow suffisante (2+)
- Bridge: flexible

### French Pronunciation Pitfalls for AI Music Generation

Known issues when Suno renders French lyrics:

| Issue | Examples | Mitigation |
|-------|----------|------------|
| Silent letters | "temps" /tɑ̃/, "corps" /kɔʁ/, "doigt" /dwa/ | Flag words with >2 silent letters per line |
| Nasal vowels | "on" /ɔ̃/, "en" /ɑ̃/, "un" /œ̃/, "in" /ɛ̃/ | No reliable fix; avoid clustering nasals |
| Liaisons | "les amis" /le.za.mi/ | Suno handles common liaisons; avoid rare ones |
| E muet ambiguity | "belle" — 1 or 2 syllables? | Suno uses spoken French (1 syl), verse rules may differ |
| Homographs | "fils" (son) vs "fils" (threads) | Context usually resolves; flag if ambiguous |

## English Linguistic Rules (Foundation for Stubs)

### Syllable Counting

English syllable counting is stress-based, not purely syllabic like French.

**Core principle:** Count vowel sounds, not vowel letters. Each distinct vowel sound = one syllable.

**Stress patterns in songwriting:** Stressed syllables align with strong beats. The stress pattern is more important than raw syllable count in English songwriting. A misaligned stress sounds worse than an extra syllable.

**Common exceptions:**
- Silent e: "name" = 1 syllable (the e is silent)
- Consecutive vowels: "beautiful" = 3 syllables (beau-ti-ful), not 4
- -ed endings: "walked" = 1 syllable, "wanted" = 2
- -tion/-sion: always 1 syllable ("na-tion" = 2 total)

### English Rhyme Types

| Type | Definition | Examples | Usage |
|------|-----------|----------|-------|
| **Perfect** (true/full) | Identical sounds from final stressed vowel to end | cat/bat, night/light, running/gunning | Choruses, hooks, emphasis |
| **Slant** (half) | Partial sound match, shares some phonetic elements | time/mine, soul/cool | Modern genres, sophistication |
| **Near** (imperfect) | Similar but not identical ending sounds | hold/bald, summer/number | Hip-hop, R&B, indie |
| **Eye** | Look alike in spelling but sound different | love/move, cough/through | Rarely intentional in song |
| **Internal** | Rhymes within a line, not at line endings | "I wake and take", "the rain in Spain" | Flow, lyrical skill, rap |

**Quality standard (per user decision):** Near/slant rhymes are fully acceptable in modern songwriting. Not all rhymes need to be perfect.

### Rhyme Schemes

| Pattern | Name | Typical Usage |
|---------|------|---------------|
| AABB | Couplets | Pop choruses, children's songs, rap |
| ABAB | Alternating | Verses (most genres), ballads |
| ABCB | Common hymn | Folk, country, simple pop verses |
| ABBA | Enclosed | Art pop, more literary/complex feel |
| AABA | 32-bar form | Jazz standards, classic pop |

### Genre-Dependent Adjustments

| Genre | Syllables/Line | Rhyme Strictness | Notes |
|-------|---------------|-------------------|-------|
| Rap | 8-16+ | Slant/near preferred | Internal rhymes valued; multisyllabic rhymes prized |
| Pop | 6-10 | Perfect preferred | Singability prioritized over complexity |
| Ballad | 6-8 | Perfect/near | Fewer syllables, more emotional space |
| Rock | 6-12 | Mixed | Depends on subgenre; punk = shorter, prog = longer |
| R&B | 8-12 | Slant/near | Smooth flow over strict rhyme |

## Sonic Toolkit (Beyond Rhyme)

Per user decision, the linguistic references should document these additional quality indicators:

| Device | Definition | Example | Quality Indicator |
|--------|-----------|---------|-------------------|
| **Assonance** | Repeated vowel sounds | "the rain in Spain" (long a) | Creates internal musicality |
| **Alliteration** | Repeated consonant sounds at word starts | "dark deep desire" | Adds rhythmic punch |
| **Consonance** | Repeated consonant sounds anywhere | "luck and lick" (k sounds) | Creates texture and cohesion |
| **Internal rhyme** | Rhyme within a line | "I bring the sting of a king" | Richness indicator, especially in rap |

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| French phonetic transcription | Custom IPA conversion rules | Claude's linguistic knowledge + IPA examples in reference files | Phonetic transcription is deceptively complex; give Claude reference examples and let it apply them |
| Suno constraint validation | Mental arithmetic on character counts | Explicit character count instructions in production brief template | Silent truncation is the #1 Suno failure mode |
| Rhyme quality classification | Ad-hoc "sounds like it rhymes" | Formal phoneme counting system defined in reference files | Orthographic similarity ≠ phonetic similarity, especially in French |

## Common Pitfalls

### Pitfall 1: CLAUDE.md Bloat
**What goes wrong:** CLAUDE.md grows past 200 lines as rules accumulate. Claude starts ignoring rules in the middle of the file.
**Why it happens:** Natural tendency to add "one more rule" without pruning.
**How to avoid:** Keep CLAUDE.md under 200 lines. Reference files hold the details. CLAUDE.md says "check reference/suno/format.md for constraints" — it does not list the constraints.
**Warning signs:** CLAUDE.md exceeding 150 lines. Duplicate information between CLAUDE.md and reference files.

### Pitfall 2: Stale Character Limits in Reference Files
**What goes wrong:** Reference file documents V4 limits (200 chars style, 3000 chars lyrics) while the project uses V5.5 (1000/5000). Production briefs are unnecessarily constrained or, worse, fail when actual limits change.
**Why it happens:** Suno limits changed across versions. Earlier research cited older numbers.
**How to avoid:** Document both the hard limit AND the practical sweet spot. Include `last-updated` metadata in every reference file. The update policy in CLAUDE.md instructs that reference files get updated, not CLAUDE.md itself.
**Warning signs:** Style prompts being artificially truncated to 200 chars when 1000 is available.

### Pitfall 3: French Rules Written for Reading, Not for AI Verification
**What goes wrong:** Linguistic rules are written as prose explanations that a human linguist would understand, but Claude cannot execute as step-by-step verification. "The e muet is complex and context-dependent" is informative but not actionable.
**How to avoid:** Every rule must be executable: "IF the word ends in -e AND the next word starts with a consonant, THEN count the -e as one syllable." Include worked examples showing step-by-step application.
**Warning signs:** Rules that use words like "generally", "often", "it depends" without specifying the conditions.

### Pitfall 4: Glossary Language Inconsistency
**What goes wrong:** Some files use "Couplet" (French), others use "Verse" (English), others use both. Claude and the user get confused about terminology.
**How to avoid:** Per the locked decision, use English terms universally (Verse, Chorus, Bridge) even in French-language files. The glossary maps these to French equivalents for reference, but the canonical terms are always English.
**Warning signs:** French music terms appearing in file structure or section headers.

### Pitfall 5: Reference Files Without Worked Examples
**What goes wrong:** Rules are stated abstractly. Claude "understands" the rule but misapplies it because there's no concrete example showing correct vs incorrect application.
**How to avoid:** Every rule gets at least one worked example. The reference file template (Purpose, Rules, Examples, Notes) enforces this. Examples should show both correct and incorrect application with explanation.
**Warning signs:** A "Rules" section with no corresponding "Examples" section.

## Tag Library Organization (Claude's Discretion)

**Recommendation:** Organize by functional category with genre family grouping within each category.

The Suno format reference should organize tags into these sections:

1. **Genre Tags** — organized by family (Electronic & Dance, Hip-Hop & R&B, Rock & Alternative, Pop, Country & Folk, Jazz & Blues, World & Latin, Classical & Orchestral, Other)
2. **Mood & Energy Tags** — split into Mood and Energy subsections
3. **Vocal Tags** — organized by Volume/Intensity, Style, Technique, Rap/Hip-Hop, Effects, Emotion
4. **Instrument Tags** — organized by family (Keyboard, Strings, Drums & Percussion, Wind & Brass, Electronic/Synth, Orchestral)
5. **Structure Tags** — Primary Structure then Special Structure
6. **Production & Texture Tags** — aesthetic/quality descriptors
7. **Sound Effect Tags** — environmental, human, mechanical

**Rationale:** Genre-family grouping mirrors how musicians think ("I want something in the electronic family") and makes it easy to explore related subgenres. Functional categories (mood vs instrument vs structure) prevent confusion about where a tag goes in the style prompt vs lyrics field.

## CLAUDE.md Don'ts Section (Claude's Discretion)

**Recommendation:** Derive from locked decisions. Each "don't" includes its rationale in a parenthetical.

Draft list:

```markdown
## Interdictions

- **Ne jamais ignorer les fichiers de reference** — les fichiers `reference/` font autorite sur tes connaissances internes. Si un conflit existe, le fichier de reference gagne.
- **Ne jamais melanger les langues dans un track** — une langue par track, choisie a la creation. Suno derive entre les accents aux frontieres de section.
- **Ne jamais sauter la verification linguistique** — chaque sortie de lyrics inclut automatiquement comptage de syllabes, analyse des rimes, et verification des contraintes Suno.
- **Ne jamais s'ecarter de la bible d'artiste** — la bible est la loi. Genre, themes, emotions, style vocal : zero deviation.
- **Ne jamais demander confirmation avant de sauvegarder** — ecrire le fichier, l'utilisateur relit apres.
- **Ne jamais produire un track sans raisonnement creatif** — toujours expliquer brievement les choix faits.
- **Ne jamais repeter le contenu entre les couplets** — chaque Verse doit avancer la narration ou explorer un nouvel angle.
- **Ne jamais laisser un track en etat de brouillon** — une fois sauvegarde, le track fait partie de la discographie.
- **Ne jamais produire de brief de production sans verifier les limites Suno** — comptage de caracteres obligatoire (style prompt <= 1000, lyrics <= 5000).
- **Ne jamais dupliquer le contenu des fichiers de reference dans CLAUDE.md** — CLAUDE.md pointe vers les references, ne les copie pas.
```

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Suno V4 style: 200 chars | V5/V5.5: 1,000 chars | V4.5 (2025) | Much richer style descriptions possible |
| Suno V4 lyrics: 3,000 chars | V5/V5.5: 5,000 chars | V4.5 (2025) | Longer songs possible, but quality degrades past ~3,000 |
| Suno Personas (style capture) | Suno Voices (voice capture) | V5.5 (March 2026) | More faithful vocal reproduction; anti-deepfake verification |
| `.claude/commands/` | `.claude/skills/` | 2025 | Skills add frontmatter, supporting files, subagent isolation |
| JSON artist bibles | Markdown with YAML frontmatter | Project decision | Better Claude compatibility, human readability |

## Open Questions

1. **V5.5 Duration Limit: 4 min or 8 min?**
   - What we know: Official Suno help says V4.5/V5 = 8 min. One source says V5.5 = 4 min per generation.
   - What's unclear: Whether V5.5 reduced the single-generation limit from 8 to 4 minutes.
   - Recommendation: Document as "up to 4-8 minutes per generation depending on version" with a note to verify. For this project, 3-4 minute tracks are the practical target anyway.

2. **Style Prompt Silent Truncation Threshold**
   - What we know: API limit is 1,000 chars. One source claims truncation at ~200 chars.
   - What's unclear: Whether the UI truncates earlier than the API, or whether the 200-char claim is outdated V4 info.
   - Recommendation: Document the 1,000-char API limit as authoritative. Recommend staying under 500 chars as the sweet spot. Front-load important tags regardless.

3. **E Muet in Modern/Rap Lyrics vs Classical Verse**
   - What we know: Classical French versification has strict e muet rules. Modern rap/spoken word relaxes these.
   - What's unclear: Exactly which rules to relax for which genres.
   - Recommendation: Document classical rules as the default. Add a "Genre Adjustments" section noting that rap/spoken word allows spoken-French syllable counting (where e muet is almost always silent). Phase 5 will refine this.

## Sources

### Primary (HIGH confidence)
- [Suno API Documentation](https://docs.sunoapi.org/suno-api/generate-music) — Character limits by model version (style, lyrics, title)
- [Suno Official Help: What's New in V5.5](https://help.suno.com/en/articles/11362305) — Voices, Custom Models, My Taste features
- [Suno Official Help: Personas](https://help.suno.com/en/articles/3484161) — Persona creation and usage
- [Suno Official Help: Song Duration](https://help.suno.com/en/articles/2409473) — Duration limits by model version
- [Suno Official Blog: V5.5](https://suno.com/blog/v5-5) — V5.5 announcement and features

### Secondary (MEDIUM confidence)
- [HookGenius: Suno Metatags Complete List](https://hookgenius.app/learn/suno-metatags-complete-list/) — Comprehensive metatag reference, cross-verified
- [HookGenius: Suno Custom Mode Guide](https://hookgenius.app/learn/suno-custom-mode-guide/) — Style prompt formula, formatting best practices
- [HookGenius: Suno Character Limits](https://hookgenius.app/learn/suno-character-limits/) — Practical limits and truncation behavior
- [HookGenius: Suno Prompt Guide 2026](https://hookgenius.app/learn/suno-prompt-guide-2026/) — Tag ordering, sweet spots, duration control
- [HookGenius: Fix Suno Pronunciation](https://hookgenius.app/learn/fix-suno-pronunciation/) — Phonetic spelling techniques
- [Musci.io: Suno Tags Complete Guide](https://musci.io/blog/suno-tags) — Genre, mood, instrument, vocal tag library
- [Blake Crosley: Suno Definitive Technical Reference](https://blakecrosley.com/guides/suno) — Tag format, placement rules, parameterization
- [Jack Righteous: Suno Multilingual Guide](https://jackrighteous.com/en-us/blogs/guides-using-suno-ai-music-creation/suno-v5-multilingual-english-pronunciation-guide) — Language handling, pronunciation
- [HookGenius: Multi-Language Guide](https://hookgenius.app/guide/multi-language) — Style prompt always in English, language detection
- [La Culture Generale: Rimes](https://www.laculturegenerale.com/rimes-pauvre-rimes-riche-qualite-richesse/) — French rhyme classification
- [Merco6: French Classical Poetry Rules](https://merco6.com/how-to-write-french-classical-poetry-rules-verses-meters/) — E muet, dierese, synerese, hiatus
- [RHYMEBOOK: Types of Rhymes](https://www.rhymebook.com/guides/types-of-rhymes) — English rhyme type definitions
- [DEV.to: CLAUDE.md Best Practices](https://dev.to/cleverhoods/-claudemd-best-practices-7-formatting-rules-for-the-machine-3d3l) — Formatting rules, section structure, emphasis usage
- [Claude Code Docs: Best Practices](https://code.claude.com/docs/en/best-practices) — Official CLAUDE.md guidance

### Tertiary (LOW confidence)
- [HookGenius: V5.5 Guide](https://hookgenius.app/learn/suno-v5-5-guide/) — V5.5 generation limit claim (4 min) needs validation
- Community guides on Suno pronunciation for non-English languages — limited French-specific data available

## Metadata

**Confidence breakdown:**
- Suno V5.5 specs (limits, metatags, features): **HIGH** — API docs + official help center + cross-verified community sources
- CLAUDE.md structure: **HIGH** — Official Claude Code docs + established best practices
- French linguistic rules: **HIGH** — Well-established prosody rules from authoritative French linguistic sources
- English linguistic rules: **HIGH** — Standard songwriting/poetry knowledge
- Suno language handling: **MEDIUM** — Community sources only, no official documentation
- Suno duration control: **MEDIUM** — Conflicting sources on V5.5 limits
- Tag library completeness: **MEDIUM** — Compiled from 4+ sources, but community-curated (no official Suno tag list exists)

**Research date:** 2026-04-10
**Valid until:** 2026-05-10 (30 days — Suno specs may change with updates; linguistic rules are stable indefinitely)
