From 2d19e2ed44e1235eedec693ea0d46b94f7cf0a2a Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 10 Aug 2026 11:15:17 -0400 Subject: [PATCH 1/5] fix(songwriting): adjudicate phrasing, song-forms, bridge, and exercises against Essential Guide to Lyric Form and Structure chapters 1, 2, and 6 Opens Book 1. Chapters 1, 2, and 6 read in full with every figure, plus Chapter 5's bridge and song-system span. Settles the two claims the 0.8.2 pass had to leave standing, both of which turned out to be wrong. "Four times is a lot" is 2009's warning alone; 1991 Chapter 6 never counts verses. "Southern Comfort" has eight verse phrases, not seven with an eighth withheld -- the eighth arrives and refuses the expected close, which is what makes it a Deceptive Closure. That also dissolves the form.md standoff: both books read eight, differing only in vocabulary. song-forms.md had recorded Chapter 6 as having no linked images. It has 37, and the chapter's entire scansion argument lives in them -- which is how the seven-phrase error survived a previous pass. Also: the three bridge functions are Chapter 6's, not Chapter 5's (Book 1 carries two different bridge lists); "different-size system" belongs to the song system, not the bridge; phrasing.md's appended block restated Chapter 1's spotlight use and got it wrong where the earlier section had it right; the even/odd balance rule shipped without either of Pattison's own overrides; and Chapter 2's three exercises were missing from a file claiming to preserve Chapters 1-7. Paraphrase only. No chapter prose, example lyrics, or exercise answers. Co-authored-by: Claude Opus 5 (1M context) --- .../songwriting/.claude-plugin/plugin.json | 2 +- plugins/songwriting/CHANGELOG.md | 86 +++++++++++++++++++ .../context/pat-pattison/research/bridge.md | 30 +++++-- .../pat-pattison/research/exercises.md | 45 +++++++++- .../research/five-compositional-elements.md | 3 +- .../context/pat-pattison/research/form.md | 21 +++-- .../context/pat-pattison/research/phrasing.md | 75 ++++++++++++---- .../research/song-forms-examples.md | 35 +++++--- .../pat-pattison/research/song-forms.md | 38 +++++--- 9 files changed, 279 insertions(+), 56 deletions(-) diff --git a/plugins/songwriting/.claude-plugin/plugin.json b/plugins/songwriting/.claude-plugin/plugin.json index 37daaa056..907f04bfa 100644 --- a/plugins/songwriting/.claude-plugin/plugin.json +++ b/plugins/songwriting/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "songwriting", - "version": "0.8.2", + "version": "0.8.3", "description": "Songwriting craft companion — nine concern-scoped lyric-craft skills (workflow router, rhyme, object-writing, metaphor, meter-prosody, song-form, co-write, diagnose, practice) applying Pat Pattison's methods, with an object-writing agent that performs the sensory exercise itself and per-skill emission boundaries that route generation to the skill that owns it, plus Suno v5.5 prompt engineering (style prompts, tagged lyrics, genre templates, troubleshooting).", "author": { "name": "Melodic Software", diff --git a/plugins/songwriting/CHANGELOG.md b/plugins/songwriting/CHANGELOG.md index 61911dc54..aba5ed9b0 100644 --- a/plugins/songwriting/CHANGELOG.md +++ b/plugins/songwriting/CHANGELOG.md @@ -3,6 +3,92 @@ All notable changes to the `songwriting` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.8.3] + +A source-fidelity pass over *Essential Guide to Lyric Form and Structure* +(1991) Chapters 1, 2, and 6, each read in full with every figure, plus +Chapter 5's bridge and song-system material. **This opens Book 1** and settles +the two claims the 0.8.2 pass had to leave standing. Paraphrase only; no +chapter prose, example lyrics, or exercise answers reach this public +repository. + +### Fixed + +- **"Four times is a lot" was credited to 1991 Chapter 6 as a shared warning. + It is 2009's alone.** Chapter 6, read in full with its 37 figures, never + discusses V/V/Ch/V/V/Ch, never counts verses, and never names four. Its + related claim is about pattern-size monotony, not verse-exposure count. + `song-forms.md` now scopes the warning to *Writing Better Lyrics* (2009), + Chapter 22, states what 1991 actually says instead, and attributes the bare + pull-quote that had been sitting uncited near the top of the file. +- **"Southern Comfort" was read as seven phrases with the eighth withheld. The + verse has eight, and the eighth arrives.** The rhyme-column and scansion + figures are unambiguous: eight phrases rhyming `x a x a x a b b`. Nothing is + withheld in phrase *count* — the eighth phrase lands and refuses the + three-stress common-meter close and the rhyme resolution the first seven set + up, which is what makes it a Deceptive Closure. Corrected in + `song-forms-examples.md` and `song-forms.md`. +- **The resulting standoff in `form.md` is dissolved, not re-hedged.** 0.8.2 + recorded 2009 Chapter 20's "two common-meter systems" and the 1991 "seven + phrases" reading as two coexisting readings not to be merged. With the 1991 + text verified, both books read **eight**; they differ only in vocabulary + (extra stress in the final phrase vs. deceptive closure). The instruction to + keep the counts apart is removed. +- **`song-forms.md` claimed 1991 Chapter 6 has no linked images. It has 37, and + they carry the argument.** The chapter's entire scansion and rhyme-column + analysis lives in figures; the text layer trails off at dangling colons. That + bad inventory line is how the seven-phrase error survived. The entry now + states the count and warns that a text-only audit will miscount phrases. +- **The three bridge functions were cited to Chapter 5; they are Chapter 6's.** + Book 1 carries two different bridge lists and the plugin had merged their + labels. `bridge.md` now cites Chapter 6 for the three purposes, and records + Chapter 5's separate five-point characterization of what a bridge *is* so the + two stop being conflated. Same fix in `song-forms-examples.md` and + `song-forms.md`. +- **"Different-size system" had been relocated from the song system to the + bridge.** Chapter 6's point is that a bridge shorter than a verse makes the + final *song system* shorter than the ones before it, so the next section + arrives early. `bridge.md` and `song-forms-examples.md` had it as the bridge + using a phrase count or line length not seen elsewhere — which contradicted + `form.md`, where the claim was already correct. +- **`phrasing.md` stated Chapter 1's spotlight use twice and got it wrong the + second time.** The early section has it right — the balancing position is the + last phrase of an *even* section, and stopping is what spotlights. The later + appended block said the balance *shift* is the spotlight, which is Chapter + 1's third use, not its first. Fourth file found with this + correct-early/wrong-late shape. +- **The even/odd balance rule was stated without either of Pattison's own + overrides.** Nesting can rescue an odd count (the five-phrase "Fathers and + Sons" verse seems balanced because two short phrases add up to one long one); + closure behavior can unbalance an even one ("Southern Comfort" at eight). + Applied mechanically, the bare rule misdiagnoses both of his examples. +- **Acceleration and deceleration were presented as an exclusive choice.** The + "Slow Healing Heart" case speeds up, returns to pace, then slows; Pattison is + explicit that more than one blank gets filled. The practice method said to + pick one label. +- **"The spotlight effect is multiplicative, not additive" is not Pattison's + claim.** He says the surprise phrase spotlights both lines, *especially* the + last. The invented framing and the dropped ranking are both corrected. +- **Chapter 2's exercises were missing entirely.** `exercises.md` claims to + preserve the numbered series for Chapters 1-7, but ran 1, 2, 3, 4 and then + jumped to 8 — the gap is exactly Chapter 2's three. Added Ex 5 (label the + pace effect, filling more than one blank where earned), Ex 6 (complete a + section accelerating, then decelerating), and Ex 7 (contrast a whole section + by phrase length), generalized in the style of Ex 1-4. +- Doubled year in two headings (`exercises.md`, `five-compositional-elements.md`) + left by a mechanical book-title substitution. + +### Added + +- `phrasing.md` — two unbalanced sections can balance each other; Pattison's + stated use for motion pairs one unbalanced section with another equally + unbalanced one, so odd sections need not be discharged by an even one. +- `phrasing.md` — the reversal test: swap a verse pair and see whether the push + survives. If it does not change, the imbalance is not doing the work. +- `song-forms.md` — Chapter 6 states its two form principles as a pair. AABA + runs on the limerick's principle and verse/chorus on Common Meter's, also + called the Ballad Stanza; only the first half was recorded. + ## [0.8.2] A source-fidelity pass over `process.md`, `co-writing.md`, and the co-write diff --git a/plugins/songwriting/context/pat-pattison/research/bridge.md b/plugins/songwriting/context/pat-pattison/research/bridge.md index 6ca298e5f..eb2ba099a 100644 --- a/plugins/songwriting/context/pat-pattison/research/bridge.md +++ b/plugins/songwriting/context/pat-pattison/research/bridge.md @@ -1,8 +1,8 @@ # Bridge Writing Pat Pattison - *Songwriting: Essential Guide to Lyric Form and Structure* -(1991), Chapter 5; *Writing Better Lyrics* (2009), Chapters 22-23. Bridge as a -developmental section: most unbalanced, structurally distinct, content-new. +(1991), Chapters 5-6; *Writing Better Lyrics* (2009), Chapters 22-23. Bridge as +a developmental section: most unbalanced, structurally distinct, content-new. ## Core idea @@ -16,21 +16,37 @@ If a writer adds a "bridge" that uses the verse's phrase count, line length, rhyme scheme, and content angle, that isn't a bridge — that's another verse with different words. -## Three bridge functions (*Essential Guide to Lyric Form and Structure* (1991), Chapter 5) +## Three bridge functions (*Essential Guide to Lyric Form and Structure* (1991), Chapter 6) A bridge must serve **at least one**, often all three: 1. **Break monotony** — the song has been in established structure too long; - the bridge contrasts to reset the ear -2. **Different-size system** — bridge uses a phrase count or line length not - seen elsewhere; the new size says "we're somewhere new" + the bridge contrasts to reset the ear, and sets up the section after it as + a contrasting arrival +2. **Different-size song system** — the different size belongs to the *system*, + not to the bridge's own dimensions. Without a bridge every song system is + one verse long; a bridge that is shorter than a verse (as most are) makes + the final system shorter than the ones before it, so the last chorus or + verse arrives "early" and gains interest from the change of pace 3. **New perspective** — bridge says something the verses haven't said. Often the "why" — the underlying cause or stakes the song has only - implied so far + implied so far. Chapter 6 frames it as letting the established ideas + "breathe" by moving to a new angle Diagnose a draft bridge: which of these three does it do? If none, it isn't bridging — it's restating. Rewrite or remove. +**Do not confuse this list with Chapter 5's.** Book 1 carries two bridge lists +and they answer different questions. Chapter 6's three purposes above are what +*adding* a bridge accomplishes for a form. Chapter 5 gives a separate +**five-point characterization of what a bridge is**: it is a developmental +section; it develops a new perspective or contrasting idea; it unbalances by +moving away from established structures, creating structural tension; it is +resolved by the return to established structures; and it is therefore +frequently the lyric's most unbalanced section. Chapter 5 also notes the +section is often called a "release" or boredom breaker — and that it is much +more than that. Cite Chapter 6 for the purposes, Chapter 5 for the definition. + ## When a song needs a bridge | Song shape | Bridge needed? | diff --git a/plugins/songwriting/context/pat-pattison/research/exercises.md b/plugins/songwriting/context/pat-pattison/research/exercises.md index d4b2485be..1331b374b 100644 --- a/plugins/songwriting/context/pat-pattison/research/exercises.md +++ b/plugins/songwriting/context/pat-pattison/research/exercises.md @@ -1,4 +1,4 @@ -# Exercises — *Essential Guide to Lyric Form and Structure* (1991) (1991) and *Essential Guide to Rhyming* (2014) (2014) +# Exercises — *Essential Guide to Lyric Form and Structure* (1991) and *Essential Guide to Rhyming* (2014) Pat Pattison — preserves the numbered exercise series from *Songwriting: Essential Guide to Lyric Form and Structure* (1991) @@ -25,7 +25,10 @@ reproducing the book. The exercises are not assessments. They are repetitions. The specific answers do not matter; the writing habit does. -## *Essential Guide to Lyric Form and Structure* (1991) — Phrasing exercises +## *Essential Guide to Lyric Form and Structure* (1991) — Phrasing exercises (Chapters 1-2) + +Exercises 1-4 come from Chapter 1 (phrase count and balance); exercises 5-7 +come from Chapter 2 (phrase length and speed). ### Ex 1 — Phrase division @@ -62,6 +65,44 @@ right for the song? Routes to: [phrasing](phrasing.md), [verse development](verse-development.md). +### Ex 5 — Label the pace effect + +Take four sections you did not write — from your own back catalogue, a +hymnal, a poetry anthology, anything with line breaks. For each, mark +whether the phrase lengths keep the pace **constant**, **accelerate**, or +**decelerate**. + +**Fill in more than one blank when the section earns it.** At least one +section in any honest sample will speed up somewhere and slow down +somewhere else. Mark where each change happens, not just that it does. +A section that changes speed twice and gets one label has been misread. + +Routes to: [phrasing](phrasing.md) "acceleration", "deceleration". + +### Ex 6 — Complete a section two ways + +Write two opening phrases of your own, then finish the section twice: +once so it **accelerates**, once so it **decelerates**. Change only +phrase length to do it — not imagery, not rhyme. + +Then check the count: if dropping the final phrase would leave the +section unbalanced, note it. Speed and balance are separate axes and a +section can be fast and unbalanced at the same time. + +Routes to: [phrasing](phrasing.md) "phrase length controls speed". + +### Ex 7 — Contrast a whole section + +Write a complete section. Then continue it with a **second section built +from shorter phrases**, choosing ideas that suit a faster pace. Then go +back and write a **slower section with longer phrases** instead. + +Aim for prosody both times: the ideas should behave the way the phrase +lengths behave. Balanced or unbalanced, whichever fits. Sing both. + +Routes to: [phrasing](phrasing.md) "contrasting sections by length", +[prosody](prosody.md). + ## *Essential Guide to Lyric Form and Structure* (1991) — Meter exercises (Chapter 3) ### Ex 8 — Syllable division diff --git a/plugins/songwriting/context/pat-pattison/research/five-compositional-elements.md b/plugins/songwriting/context/pat-pattison/research/five-compositional-elements.md index f8591b0d5..e648095ac 100644 --- a/plugins/songwriting/context/pat-pattison/research/five-compositional-elements.md +++ b/plugins/songwriting/context/pat-pattison/research/five-compositional-elements.md @@ -213,7 +213,8 @@ balls (not five) are introduced sequentially: - Ball 3 (Chapter 3) — rhythm - Ball 4 (Chapter 4) — rhyme scheme -The **fifth element (rhyme type)** was added in *Essential Guide to Rhyming* (2014) (2014). *Essential Guide to Lyric Form and Structure* (1991) +The **fifth element (rhyme type)** was added in *Essential Guide to Rhyming* +(2014). *Essential Guide to Lyric Form and Structure* (1991) intentionally uses only **perfect rhyme and identity** for all 44 exercises — no family, additive, assonance, or consonance vocabulary. diff --git a/plugins/songwriting/context/pat-pattison/research/form.md b/plugins/songwriting/context/pat-pattison/research/form.md index 0d1f04711..9872941cd 100644 --- a/plugins/songwriting/context/pat-pattison/research/form.md +++ b/plugins/songwriting/context/pat-pattison/research/form.md @@ -203,12 +203,21 @@ leans toward the meter the verse has already established at length. Where a chorus is meant to contrast with a common-meter verse, check what its balancing phrases are doing, not only whether the numbers differ. -On how many verse phrases that is: Chapter 20 reads the verse as two complete -common-meter systems varied by an extra stress in its last phrase, while -[song-forms-examples](song-forms-examples.md) reads the 1991 treatment of the -same song as seven phrases with the closing eighth deceptively withheld. Those -are two readings of one verse in two books, not a contradiction to resolve — -cite whichever book is in hand and do not merge the counts. +On how many verse phrases that is: **the two books agree at eight, and the +apparent standoff was our error, not Pat's.** *Writing Better Lyrics* (2009), +Chapter 20 reads the verse as two complete common-meter systems — eight lines — +varied by an extra stress in its last phrase. *Essential Guide to Lyric Form +and Structure* (1991), Chapter 6, read with its figures, sets the same verse out +as eight phrases rhyming `x a x a x a b b` and calls the last phrase a +Deceptive Closure. + +Same structure, two vocabularies: what 2009 describes as an extra stress in the +final phrase, 1991 describes as that phrase refusing the three-stress +common-meter close the first seven have set up. Nothing is withheld in phrase +*count* — the eighth phrase arrives and deceives. An earlier revision of +[song-forms-examples](song-forms-examples.md) read it as seven phrases with the +eighth withheld; that reading is corrected, and there is no longer a reason to +keep the counts apart. Useful revision moves: diff --git a/plugins/songwriting/context/pat-pattison/research/phrasing.md b/plugins/songwriting/context/pat-pattison/research/phrasing.md index 28e3db996..fad3b7842 100644 --- a/plugins/songwriting/context/pat-pattison/research/phrasing.md +++ b/plugins/songwriting/context/pat-pattison/research/phrasing.md @@ -71,6 +71,25 @@ Even phrase counts feel balanced. Odd phrase counts feel unbalanced. Balanced sections tend to stop motion. Unbalanced sections create motion because the listener expects a balancing phrase that has not arrived. +**Parity is the default, not the verdict.** Pattison overrides it in both +directions with his own examples, so count parity first and then check two +things before calling a section balanced: + +- **Nesting can rescue an odd count.** The first verse of "Fathers and Sons" + runs five phrases and still *seems* balanced, because two of its short + phrases add up to one long one — the two-level counting above doing real + work. Pattison notes the verse is close to limerick form, and that once + lyrics are set to music the musical rhythms dominate and the limerick feeling + is shaded. +- **Closure behavior can unbalance an even count.** The verse of "Southern + Comfort" runs eight phrases — even — and is still unbalanced, because its + last phrase refuses the three-stress close and the rhyme resolution the + earlier phrases set up. See [song-forms-examples](song-forms-examples.md). + +An agent that applies parity mechanically misdiagnoses both of Pattison's own +cases. Count, then ask whether the short phrases group and whether the last +phrase actually closes. + Use that deliberately: - Balance to land an idea. @@ -110,18 +129,32 @@ Phrase A intensified The same effect can happen with three different phrases if they share a clear shape. The listener still wants a balancing position. +**Two unbalanced sections can balance each other.** Pattison's stated use for +motion is connecting one unbalanced section to another equally unbalanced one — +his worked case pairs three phrases with three more. The pressure that an odd +section builds does not have to be discharged by an even section; it can be +answered by a matching odd section, which balances at the pair level while both +halves stay in motion internally. + ## Contrast sections Balance can change across verses. A first verse can be fully balanced so it settles; a second verse can add one extra phrase so it pushes into the chorus. Worked example: Pattison points to Kevin Cronin's "Can't Fight This Feeling." -The first verse balances. The second verse adds a phrase near the end, tipping -the structure forward and making the chorus feel like the needed landing point. +The first verse balances at four phrases. The second verse adds a fifth near the +end, tipping the structure forward and making the chorus feel like the needed +landing point. + +**The reversal test.** Pattison's own check on this example: swap the two +verses and the motion stops. If reversing a pair of verses does not change how +hard the section pushes, the imbalance is not doing the work you think it is. +Order the pair so the unbalanced one sits second. This also works inside a repeated verse form: an extra final phrase can surprise the ear, spotlight the normal balanced position, and then spotlight the added -line even more strongly. +line even more strongly. In "The Great Pretender" the balanced verse runs four +phrases and the contrasting one runs five. ## Phrase length controls speed @@ -217,7 +250,12 @@ For any draft section: 3. Count short phrase units. 4. Count larger phrase groups. 5. Mark which position currently spotlights the strongest idea. -6. Label phrase lengths as constant, accelerating, or decelerating. +6. Label phrase lengths as constant, accelerating, or decelerating — and use + **more than one label when the section needs it.** These are not mutually + exclusive. Pattison's "Slow Healing Heart" case speeds up, returns to its + earlier pace, then slows relative to the original phrase length, and he is + explicit that you have to fill in more than one blank. A single label on a + section that changes speed twice hides the thing worth seeing. 7. Decide whether the section should stop, lean forward, speed up, or slow down. ## Revision moves @@ -327,14 +365,18 @@ this line walk forward" lands faster than "make this line back-heavy". ## Three-use balance taxonomy (*Essential Guide to Lyric Form and Structure* (1991), Chapter 1) -Pat's *Essential Guide to Lyric Form and Structure* (1991), Chapter 1 lists three deliberate uses for balanced and unbalanced -phrase counts. The concept is present elsewhere in the skill but the -named three-use taxonomy is *Essential Guide to Lyric Form and Structure* (1991)'s distinctive framing: - -1. **Spotlight** — use balance/unbalance to draw attention to a specific - line or section. The balance shift IS the spotlight. A section that - was balanced suddenly becoming unbalanced makes the listener notice - the change. +Pat's *Essential Guide to Lyric Form and Structure* (1991), Chapter 1 names +**at least three** deliberate uses for balanced and unbalanced phrase counts — +his phrasing is "at least three purposes," so treat the list as open rather +than as a closed taxonomy. The concept is present elsewhere in the skill; the +named grouping is 1991's distinctive framing: + +1. **Spotlight** — this one is about *position*, not about change. When a + section has an even number of phrases, the last phrase is the balancing + position: the place where the lyric structure stops moving. Stopping is what + shines the spotlight, so whatever lands there gets the attention. Decide + which idea matters most, then put it in that slot. (The *shift* from + balanced to unbalanced is use 3, not use 1 — do not merge them.) 2. **Push sections forward** — use unbalance to refuse closure. An odd phrase count leaves the listener wanting more; that want IS the forward push. Balance closes; imbalance opens. @@ -343,10 +385,11 @@ named three-use taxonomy is *Essential Guide to Lyric Form and Structure* (1991) distinct. A balanced verse + unbalanced bridge contrasts on the balance axis itself, independent of content. -Pat uses "The Great Pretender" (*Essential Guide to Lyric Form and Structure* (1991), Chapter 1) as an example where adding -one extra phrase to a section spotlights TWO lines more powerfully than -the extra phrase alone — the spotlight effect is multiplicative, not -additive. +Pat uses "The Great Pretender" (*Essential Guide to Lyric Form and Structure* +(1991), Chapter 1) as an example where the surprise of an extra phrase +spotlights **both** the normal balancing position and the added line — with the +last phrase getting the most of it. Two lines lit, not one, and they are not +lit equally. The three uses are not exclusive. A single balance choice can do all three at once (spotlight a specific line, push the section forward, and diff --git a/plugins/songwriting/context/pat-pattison/research/song-forms-examples.md b/plugins/songwriting/context/pat-pattison/research/song-forms-examples.md index c9d1d3cc5..bc1280067 100644 --- a/plugins/songwriting/context/pat-pattison/research/song-forms-examples.md +++ b/plugins/songwriting/context/pat-pattison/research/song-forms-examples.md @@ -34,15 +34,18 @@ that carries the title. - Forward motion: lines 1-4 build expectation; the refrain payoff lands at the structural close, not at a chorus boundary -**Bridge variant (same song, Chapter 5 demonstration):** -Pat adds a bridge to demonstrate all three *Essential Guide to Lyric Form and Structure* (1991), Chapter 5 bridge functions -point-by-point on a real song: - -1. **Break monotony** — bridge contrasts the established verse structure -2. **Different-size system** — bridge uses a phrase count or line length - not seen in the verses -3. **New perspective** — bridge says something the verses haven't said, - not a restatement +**Bridge variant (same song, Chapter 6 demonstration):** +Pat adds a bridge to demonstrate all three *Essential Guide to Lyric Form and +Structure* (1991), Chapter 6 bridge purposes point-by-point on a real song: + +1. **Break monotony** — bridge contrasts the established verse structure, and + sets up the last verse as a contrasting section +2. **Different-size song system** — with only verses, every song system is one + verse long. Adding the bridge creates a system that starts at the bridge and + ends when the last verse closes, so the lyric stops running same-size units. + The claim is about the *system's* size, not the bridge's own phrase count +3. **New perspective** — the bridge lets the verse ideas "breathe" by moving to + a new angle, rather than restating them This is the book's clearest demonstration of bridge function as a multi-purpose tool, not a structural slot. @@ -58,10 +61,16 @@ across three preceding lines. **Structural mechanics:** -- Seven phrases of Common Meter in the verse (NOT eight — that's the trick) -- The expected eighth phrase, which would close the verse with three-stress - resolution, is **deceptively withheld** -- Instead, the verse's last phrase points forward — it does not close +- **Eight phrases in the verse**, rhyming `x a x a x a b b`. The first six lock + the ear into Common Meter; the seventh only continues the pattern +- Nothing is withheld in phrase *count*. The eighth phrase **arrives** — and + refuses both the three-stress Common Meter close and the rhyme resolution + the first seven have trained the ear to expect. That refusal is the + **Deceptive Closure** +- Pat scopes it precisely: the last phrase, and the last phrase alone, + unbalances the section. Any three-stress phrase in that position would have + balanced it +- So the verse's last phrase points forward — it does not close - Chorus delivers the withheld three-stress closure AND the title's rhyme payoff - Bridge (when present) is derived from a two-stress phrase hint already diff --git a/plugins/songwriting/context/pat-pattison/research/song-forms.md b/plugins/songwriting/context/pat-pattison/research/song-forms.md index 01836568a..599a1993f 100644 --- a/plugins/songwriting/context/pat-pattison/research/song-forms.md +++ b/plugins/songwriting/context/pat-pattison/research/song-forms.md @@ -6,7 +6,13 @@ Chapter 22-23. ## Image inventory -- *Essential Guide to Lyric Form and Structure* (1991), Chapter 6: no linked images. +- *Essential Guide to Lyric Form and Structure* (1991), Chapter 6: **37 linked + images**, and they are load-bearing. Chapter 6's entire scansion and + rhyme-column argument lives in figures, not in the text layer — the prose + runs "…the seventh phrase only continues the pattern:" and then stops. Any + audit of this chapter that reads only extracted text will miscount phrases; + that is exactly how the "Southern Comfort" seven-phrase error entered this + file. Read the figures. - *Writing Better Lyrics* (2009), Chapter 22: no linked images. - *Writing Better Lyrics* (2009), Chapter 23: no linked images. @@ -27,7 +33,7 @@ base; contrast creates tension; return resolves it. helps the lyric arrive with power; it is impotent when repetition, delay, or wrong-sized sections make the message sag. -> Four times is a lot. +> "Four times is a lot." — Pat (*Writing Better Lyrics* (2009), Chapter 22) The risky case is: @@ -255,7 +261,9 @@ then feeling the arrival back at it. ## Verse / Chorus -Simple verse/chorus form works like Common Meter at the section level: +Simple verse/chorus form works like Common Meter — also called the **Ballad +Stanza** — at the section level. Chapter 6 states the two mappings as a pair: +AABA runs on the limerick's principle, verse/chorus runs on Common Meter's. ```text 1. statement A Verse @@ -530,10 +538,18 @@ without development. ## "Four times is a lot" — V/V/Ch/V/V/Ch risk -*Essential Guide to Lyric Form and Structure* (1991), Chapter 6 and *Writing Better Lyrics* (2009), Chapter 22 share a named warning: V/V/Ch/V/V/Ch form -asks the listener to absorb four verses. Four-times verse exposure +*Writing Better Lyrics* (2009), Chapter 22 names this warning: V/V/Ch/V/V/Ch +form asks the listener to absorb four verses. Four-times verse exposure risks boredom even with strong verses. +**The warning is 2009's alone.** *Essential Guide to Lyric Form and Structure* +(1991), Chapter 6 — now read in full with its figures — does not carry it. +Chapter 6 never discusses V/V/Ch/V/V/Ch, never counts verses, and never names +four. Its related-but-different claim is about *pattern-size monotony*: running +the same structural pattern too long "gets boring fast," and the remedy Pat +reaches for is a bridge. He makes that point twice — once for AABA, once for +verse/chorus. Do not cite 1991 for a verse-count threshold. + Three named repair strategies: 1. **Distill verses 3 and 4 into one stronger verse.** Combine the @@ -602,11 +618,13 @@ form's mechanics on real songs. See [song-forms-examples](song-forms-examples.md for paraphrased mechanism analyses (NOT lyric reproduction) of: - **"This Bottle and Me"** — verse/refrain with Common Meter ×2, xaxaxbxb, - fragmentation at line 4; bridge variant demonstrates all three *Essential Guide to Lyric Form and Structure* (1991), Chapter 5 - bridge functions point-by-point -- **"Southern Comfort"** — verse/chorus with deceptive closure on the - verse's seventh phrase; chorus delivers withheld three-stress resolution - - title rhyme payoff + fragmentation after line 4; bridge variant demonstrates all three *Essential + Guide to Lyric Form and Structure* (1991), Chapter 6 bridge purposes + point-by-point +- **"Southern Comfort"** — verse/chorus whose eight-phrase verse (`x a x a x a + b b`) sets up Common Meter and then refuses to close on it; the deceptive + closure lands on the verse's **eighth** phrase, and the chorus delivers the + withheld three-stress resolution plus the title rhyme payoff - **"Teddy Doesn't Live Here Anymore"** — verse/trans-bridge/chorus three-system analysis; the slingshot effect (long phrase before hook); unstressed-syllable trick implying a fifth stress; hook delivers 5-stress From d6000f957775281fe9b83a6a0fc134e0e2b6b102 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 10 Aug 2026 11:32:20 -0400 Subject: [PATCH 2/5] fix(songwriting): propagate the bridge correction to every jointly loaded consumer Addresses three review findings on #2155. "Different-size song system" said the final system gets shorter. That holds for verse/chorus, where systems 1 and 2 are verse-to-chorus and a short bridge shrinks system 3. It is backwards for verse/refrain and AABA, where the bridge groups with the last verse and makes that system LONGER than the verse-only ones before it. Pat's word is "different"; only the direction is form-specific, and what arrives early there is the final verse, not the system's end. The Chapter 5 -> Chapter 6 attribution and the phrase-count reading of function 2 had survived in form.md and bridge-writing-prompt.md, which /songwriting:song-form bridge loads alongside bridge.md. A single invocation would have supplied contradictory sourcing and diagnostics. Also corrected in audit-checklist.md and audit-checklist-prompt.md, found by sweeping for the same attribution rather than only the files the review named. Exercise 5 asserted that any honest four-section sample contains a mixed-speed section. The writer picks the sections, so nothing guarantees it, and the assertion pressures inventing a change that is not there. Multiple labels are now permitted rather than required. Two more caught by the same sweep: form.md attributed "A bridge isn't a verse" to 1991 Chapter 5, but the phrase is absent from Book 1's text layer and song-forms.md and bridge-writing-prompt.md both source it to 2009 Chapter 23. And response-filter.md said V/V/Ch/V/V/Ch runs the chorus four times; it runs the verse four times and the chorus twice. Co-authored-by: Claude Opus 5 (1M context) --- plugins/songwriting/CHANGELOG.md | 18 +++++++++++++----- .../pat-pattison/research/audit-checklist.md | 2 +- .../context/pat-pattison/research/bridge.md | 16 ++++++++++++---- .../context/pat-pattison/research/exercises.md | 10 ++++++---- .../context/pat-pattison/research/form.md | 12 +++++++++--- .../pat-pattison/research/response-filter.md | 4 ++-- .../templates/audit-checklist-prompt.md | 2 +- .../templates/bridge-writing-prompt.md | 9 ++++++--- 8 files changed, 50 insertions(+), 23 deletions(-) diff --git a/plugins/songwriting/CHANGELOG.md b/plugins/songwriting/CHANGELOG.md index aba5ed9b0..2b8b47380 100644 --- a/plugins/songwriting/CHANGELOG.md +++ b/plugins/songwriting/CHANGELOG.md @@ -46,11 +46,19 @@ repository. two stop being conflated. Same fix in `song-forms-examples.md` and `song-forms.md`. - **"Different-size system" had been relocated from the song system to the - bridge.** Chapter 6's point is that a bridge shorter than a verse makes the - final *song system* shorter than the ones before it, so the next section - arrives early. `bridge.md` and `song-forms-examples.md` had it as the bridge - using a phrase count or line length not seen elsewhere — which contradicted - `form.md`, where the claim was already correct. + bridge.** Chapter 6's claim is about the *song system's* size, not the + bridge's own phrase count or line length — and Pat's word is **different**, + not shorter. The direction depends on the form: in verse/chorus a short + bridge makes the last system shorter so the final chorus arrives early, while + in verse/refrain and AABA the bridge-plus-final-verse system is *longer* than + the verse-only systems before it. Corrected in `bridge.md`, `form.md`, and + `templates/bridge-writing-prompt.md`. +- **All four jointly loaded bridge consumers now agree.** + `/songwriting:song-form bridge` loads `bridge.md`, `form.md`, + `templates/bridge-writing-prompt.md`, and `song-forms.md` together; the + Chapter 5 attribution and the phrase-count reading of function 2 survived in + `form.md` and the template, so a single invocation would have supplied + contradictory sourcing and diagnostics. - **`phrasing.md` stated Chapter 1's spotlight use twice and got it wrong the second time.** The early section has it right — the balancing position is the last phrase of an *even* section, and stopping is what spotlights. The later diff --git a/plugins/songwriting/context/pat-pattison/research/audit-checklist.md b/plugins/songwriting/context/pat-pattison/research/audit-checklist.md index 43e59d0e2..ff280e55d 100644 --- a/plugins/songwriting/context/pat-pattison/research/audit-checklist.md +++ b/plugins/songwriting/context/pat-pattison/research/audit-checklist.md @@ -166,7 +166,7 @@ After the per-line pass, zoom out. - [ ] central section chosen (chorus or refrain — *Essential Guide to Lyric Form and Structure* (1991), Chapter 5) - [ ] title position decided - [ ] repetition strategy: chorus repaints? refrain stays exact? -- [ ] bridge present? — bridge fulfills at least one of the three *Essential Guide to Lyric Form and Structure* (1991), Chapter 5 functions (break monotony / different-size system / new perspective) +- [ ] bridge present? — bridge fulfills at least one of the three *Essential Guide to Lyric Form and Structure* (1991), Chapter 6 functions (break monotony / different-size song system / new perspective) - [ ] "four times is a lot" check (*Writing Better Lyrics* (2009), Chapter 22) — V/V/Ch/V/V/Ch risk - [ ] verse-job division clear (You-I-We? Past-Present-Future? per box-model.md) diff --git a/plugins/songwriting/context/pat-pattison/research/bridge.md b/plugins/songwriting/context/pat-pattison/research/bridge.md index eb2ba099a..8ce1a24a1 100644 --- a/plugins/songwriting/context/pat-pattison/research/bridge.md +++ b/plugins/songwriting/context/pat-pattison/research/bridge.md @@ -24,10 +24,18 @@ A bridge must serve **at least one**, often all three: the bridge contrasts to reset the ear, and sets up the section after it as a contrasting arrival 2. **Different-size song system** — the different size belongs to the *system*, - not to the bridge's own dimensions. Without a bridge every song system is - one verse long; a bridge that is shorter than a verse (as most are) makes - the final system shorter than the ones before it, so the last chorus or - verse arrives "early" and gains interest from the change of pace + not to the bridge's own dimensions. Pat's word is **different**, and the + direction depends on the form: + - *Verse/chorus.* Systems 1 and 2 each run verse → chorus. A bridge that is + shorter than a verse (most are) makes system 3 **shorter**, so the final + chorus arrives "early" and gains interest from the change of pace. + - *Verse/refrain or AABA.* Every system was one verse long. The bridge does + not shorten anything — it creates a system that starts at the bridge and + ends when the last verse closes, which is **longer** than the ones before + it. What arrives early is the final verse, not the system's end. + + Diagnose by asking what the bridge is grouped with, not by assuming the last + system shrinks 3. **New perspective** — bridge says something the verses haven't said. Often the "why" — the underlying cause or stakes the song has only implied so far. Chapter 6 frames it as letting the established ideas diff --git a/plugins/songwriting/context/pat-pattison/research/exercises.md b/plugins/songwriting/context/pat-pattison/research/exercises.md index 1331b374b..8da736f20 100644 --- a/plugins/songwriting/context/pat-pattison/research/exercises.md +++ b/plugins/songwriting/context/pat-pattison/research/exercises.md @@ -72,10 +72,12 @@ hymnal, a poetry anthology, anything with line breaks. For each, mark whether the phrase lengths keep the pace **constant**, **accelerate**, or **decelerate**. -**Fill in more than one blank when the section earns it.** At least one -section in any honest sample will speed up somewhere and slow down -somewhere else. Mark where each change happens, not just that it does. -A section that changes speed twice and gets one label has been misread. +**More than one blank is allowed.** Some sections are simply constant, or +simply accelerate — record that. But a section can also speed up in one +place and slow down in another, and Pattison's own sample includes one that +does. Where that happens, mark every change and where it falls; do not force +a single label onto a section that changes speed twice, and do not invent a +change that is not there to make the answer more interesting. Routes to: [phrasing](phrasing.md) "acceleration", "deceleration". diff --git a/plugins/songwriting/context/pat-pattison/research/form.md b/plugins/songwriting/context/pat-pattison/research/form.md index 9872941cd..e1b33f4b4 100644 --- a/plugins/songwriting/context/pat-pattison/research/form.md +++ b/plugins/songwriting/context/pat-pattison/research/form.md @@ -524,8 +524,10 @@ larger form roles and song systems. ## Bridge — three functions -*Essential Guide to Lyric Form and Structure* (1991), Chapter 5 names three jobs a bridge can do. Diagnose which the song -needs before drafting. +*Essential Guide to Lyric Form and Structure* (1991), **Chapter 6** names three +jobs a bridge can do. Diagnose which the song needs before drafting. (Chapter 5 +gives a separate five-point account of what a bridge *is* — see +[bridge](bridge.md); do not merge the two lists.) | Function | Effect | When | |---|---|---| @@ -533,6 +535,10 @@ needs before drafting. | 2. Create a different-size song system | Insert a non-matching unit between matching units | The song's symmetry needs interruption | | 3. Provide a new perspective | Shift POV, tense, or speaker | The chorus has stated; the bridge reframes | +Function 2 is about the **system's** size, not the bridge's own phrase count, +and "different" does not always mean "shorter" — in verse/chorus the final +system shrinks, in verse/refrain and AABA it grows. See [bridge](bridge.md). + A bridge that serves only one function may still work. A bridge that serves none should be cut — verse-chorus alone is enough. @@ -540,7 +546,7 @@ The bridge MUST differ from verses where it counts. The first line matters most: a bridge that opens like a verse signals "another verse" instead of "something new." -> "A bridge isn't a verse." — Pat (*Essential Guide to Lyric Form and Structure* (1991), Chapter 5) +> "A bridge isn't a verse." — Pat (*Writing Better Lyrics* (2009), Chapter 23) ## Four building levers — the candy bar discipline diff --git a/plugins/songwriting/context/pat-pattison/research/response-filter.md b/plugins/songwriting/context/pat-pattison/research/response-filter.md index 9c7dc74c6..24c7a047d 100644 --- a/plugins/songwriting/context/pat-pattison/research/response-filter.md +++ b/plugins/songwriting/context/pat-pattison/research/response-filter.md @@ -379,8 +379,8 @@ AABA", "do I need a bridge", or AI is about to recommend a song form. - [ ] **Bridge necessity tested** — does the song need to break monotony, add a different-size system, or introduce a new perspective? If none → no bridge -- [ ] **"Four-times-a-lot" check** — V/V/Ch/V/V/Ch has the chorus four - times; risk of fatigue (*Writing Better Lyrics* (2009), Chapter 22) +- [ ] **"Four-times-a-lot" check** — V/V/Ch/V/V/Ch runs the VERSE four + times (the chorus twice); risk of fatigue (*Writing Better Lyrics* (2009), Chapter 22) - [ ] **Transitional bridge (pre-chorus)** — only if a climb to chorus needs explicit lift; not by default - [ ] **Form fits melody** if a melody exists — see §2 phrasing checklist diff --git a/plugins/songwriting/context/pat-pattison/templates/audit-checklist-prompt.md b/plugins/songwriting/context/pat-pattison/templates/audit-checklist-prompt.md index 5493d644d..3daeaa3af 100644 --- a/plugins/songwriting/context/pat-pattison/templates/audit-checklist-prompt.md +++ b/plugins/songwriting/context/pat-pattison/templates/audit-checklist-prompt.md @@ -140,7 +140,7 @@ After running per-line on the section's lines, zoom out: - [ ] Central section chosen (chorus or refrain)? - [ ] Title position decided? - [ ] Repetition strategy: chorus repaints? refrain exact? -- [ ] Bridge present? — fulfills at least one *Essential Guide to Lyric Form and Structure* (1991), Chapter 5 function? +- [ ] Bridge present? — fulfills at least one *Essential Guide to Lyric Form and Structure* (1991), Chapter 6 function? - [ ] "Four times is a lot" risk checked (*Writing Better Lyrics* (2009), Chapter 22)? - [ ] Verse-job division clear (box model)? ``` diff --git a/plugins/songwriting/context/pat-pattison/templates/bridge-writing-prompt.md b/plugins/songwriting/context/pat-pattison/templates/bridge-writing-prompt.md index f090754d8..60000cee4 100644 --- a/plugins/songwriting/context/pat-pattison/templates/bridge-writing-prompt.md +++ b/plugins/songwriting/context/pat-pattison/templates/bridge-writing-prompt.md @@ -36,13 +36,16 @@ Probe the writer: Surface 2-3 candidate missing angles. Writer picks one. -## Step 3 — Three bridge functions check (*Essential Guide to Lyric Form and Structure* (1991), Chapter 5) +## Step 3 — Three bridge functions check (*Essential Guide to Lyric Form and Structure* (1991), Chapter 6) ``` A bridge must do AT LEAST ONE of: 1. **Break monotony** — contrasts established structure to reset the ear -2. **Different-size system** — phrase count / line length not seen elsewhere +2. **Different-size song system** — the SYSTEM changes size, not the bridge's + own phrase count. Verse/chorus: the last system gets shorter, so the final + chorus arrives early. Verse/refrain or AABA: bridge + last verse make a + LONGER system than the verse-only ones before it. Different, not shorter. 3. **New perspective** — says something the verses haven't said Your bridge will serve function: @@ -112,7 +115,7 @@ to 2 axes. Run per-line and per-section audit (per `audit-checklist.md`). Key bridge items: -- Bridge serves at least one *Essential Guide to Lyric Form and Structure* (1991), Chapter 5 function? +- Bridge serves at least one *Essential Guide to Lyric Form and Structure* (1991), Chapter 6 function? - Contrasts on 2-3 axes (not all 8)? - Bridge → next section feels like arrival? - Sing-check passed? From 8aa2e94d8eb2213193df782ce17321718ee0f02f Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 10 Aug 2026 12:13:50 -0400 Subject: [PATCH 3/5] fix(songwriting): correct form.md's Chapter 5 image inventory and scope two overreaching claims form.md recorded 1991 Chapter 5 as having no linked images. It has 32 (image_rsrc31Z-32Y), and like Chapter 6's 37 they carry the scansion and rhyme-scheme analysis while the prose stops at dangling colons. This is the same false-inventory defect this branch already fixed in song-forms.md for Chapter 6 -- and the same one that let the seven-phrase "Southern Comfort" error survive an earlier pass. The entry now also records that Chapter 5 has not been read in full, so claims sourced to it are not mistaken for verified. form.md's header still attributed only Chapter 5 while its body now cites Chapter 6 for the three bridge functions; book-references.md requires the header to name its sources. bridge.md said that in verse/refrain and AABA the final verse "arrives early." Chapter 6 uses the early-arrival language only in the verse/chorus passage; the verse/refrain passage claims the size change alone. Scoped to what the source says. Ex 5 asked for four sections "you did not write" and then offered the writer's own back catalogue. Co-authored-by: Claude Opus 5 (1M context) --- plugins/songwriting/CHANGELOG.md | 13 ++++++++----- .../context/pat-pattison/research/bridge.md | 3 ++- .../context/pat-pattison/research/exercises.md | 8 ++++---- .../context/pat-pattison/research/form.md | 10 ++++++++-- 4 files changed, 22 insertions(+), 12 deletions(-) diff --git a/plugins/songwriting/CHANGELOG.md b/plugins/songwriting/CHANGELOG.md index 2b8b47380..d12b52744 100644 --- a/plugins/songwriting/CHANGELOG.md +++ b/plugins/songwriting/CHANGELOG.md @@ -34,11 +34,14 @@ repository. text verified, both books read **eight**; they differ only in vocabulary (extra stress in the final phrase vs. deceptive closure). The instruction to keep the counts apart is removed. -- **`song-forms.md` claimed 1991 Chapter 6 has no linked images. It has 37, and - they carry the argument.** The chapter's entire scansion and rhyme-column - analysis lives in figures; the text layer trails off at dangling colons. That - bad inventory line is how the seven-phrase error survived. The entry now - states the count and warns that a text-only audit will miscount phrases. +- **Two image inventories claimed their 1991 chapter has no linked images. + Chapter 6 has 37 and Chapter 5 has 32, and in both the figures carry the + argument.** The scansion and rhyme-column analysis lives in the figures while + the text layer trails off at dangling colons. `song-forms.md`'s false entry is + how the seven-phrase error survived a previous pass; `form.md` carried the + same falsehood for Chapter 5. Both now state the real count. `form.md`'s entry + also records that Chapter 5 has *not* been read in full, so claims sourced to + it are not mistaken for verified. - **The three bridge functions were cited to Chapter 5; they are Chapter 6's.** Book 1 carries two different bridge lists and the plugin had merged their labels. `bridge.md` now cites Chapter 6 for the three purposes, and records diff --git a/plugins/songwriting/context/pat-pattison/research/bridge.md b/plugins/songwriting/context/pat-pattison/research/bridge.md index 8ce1a24a1..c3dd69cb0 100644 --- a/plugins/songwriting/context/pat-pattison/research/bridge.md +++ b/plugins/songwriting/context/pat-pattison/research/bridge.md @@ -32,7 +32,8 @@ A bridge must serve **at least one**, often all three: - *Verse/refrain or AABA.* Every system was one verse long. The bridge does not shorten anything — it creates a system that starts at the bridge and ends when the last verse closes, which is **longer** than the ones before - it. What arrives early is the final verse, not the system's end. + it. Chapter 6 claims only the size change here, not an early arrival; the + "early" language belongs to the verse/chorus case above. Diagnose by asking what the bridge is grouped with, not by assuming the last system shrinks diff --git a/plugins/songwriting/context/pat-pattison/research/exercises.md b/plugins/songwriting/context/pat-pattison/research/exercises.md index 8da736f20..d02e1d8a7 100644 --- a/plugins/songwriting/context/pat-pattison/research/exercises.md +++ b/plugins/songwriting/context/pat-pattison/research/exercises.md @@ -67,10 +67,10 @@ Routes to: [phrasing](phrasing.md), [verse development](verse-development.md). ### Ex 5 — Label the pace effect -Take four sections you did not write — from your own back catalogue, a -hymnal, a poetry anthology, anything with line breaks. For each, mark -whether the phrase lengths keep the pace **constant**, **accelerate**, or -**decelerate**. +Take four sections you are not currently working on — old drafts of your +own, a hymnal, a poetry anthology, anything with line breaks. For each, +mark whether the phrase lengths keep the pace **constant**, **accelerate**, +or **decelerate**. **More than one blank is allowed.** Some sections are simply constant, or simply accelerate — record that. But a section can also speed up in one diff --git a/plugins/songwriting/context/pat-pattison/research/form.md b/plugins/songwriting/context/pat-pattison/research/form.md index e1b33f4b4..6c50208f8 100644 --- a/plugins/songwriting/context/pat-pattison/research/form.md +++ b/plugins/songwriting/context/pat-pattison/research/form.md @@ -1,12 +1,18 @@ # Form Pat Pattison - *Songwriting: Essential Guide to Lyric Form and Structure* -(1991), Chapter 5. Pat Pattison - *Writing Better Lyrics* (2009), +(1991), Chapters 5-6. Pat Pattison - *Writing Better Lyrics* (2009), Chapter 20-21. ## Image inventory -- *Essential Guide to Lyric Form and Structure* (1991), Chapter 5: no linked images. +- *Essential Guide to Lyric Form and Structure* (1991), Chapter 5: **32 linked + images** (`image_rsrc31Z`-`image_rsrc32Y`), and they carry the chapter's + scansion and rhyme-scheme analysis the way Chapter 6's do. The prose stops at + dangling colons ("The first phrases play off against the rhythms, grouping + this way:"). **Chapter 5 has NOT been read in full** — only its bridge and + Song System span. Treat every claim sourced to it here as unverified until it + is, and read the figures when doing so. - *Writing Better Lyrics* (2009), Chapter 20: `image_rsrcAUG.jpg` shows a verse/chorus rhyme-column comparison for "Southern Comfort"; both sections lean on similar `x/a` alternation before the bridge arrives. From bb9585ea322fef19008c910751e4293702f52582 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 10 Aug 2026 13:18:39 -0400 Subject: [PATCH 4/5] fix(ci): stop the changelog-parity gate reporting a present entry as missing --check-bump reported "UNDOCUMENTED BUMP: songwriting went 0.8.2 -> 0.8.3 but plugins/songwriting/CHANGELOG.md has no '## [0.8.3]' entry at head" while that heading was the file's first, at line 6, outside any fence. Root cause, reproduced: has_heading runs `rendered_lines | awk` under `set -o pipefail` (line 63), and the matcher exited on its first hit. That closes the pipe while rendered_lines is still writing, rendered_lines takes SIGPIPE and exits 141, and pipefail promotes 141 to the status of the whole pipeline -- so a FOUND heading reports as absent. It only bites once the unread remainder outgrows the pipe buffer, which is why it passed on short changelogs and on the author's machine and failed in CI on the repo's longest changelog. Against a 79KB fixture the old shape returns 141 and the new one returns 0. Fixed by reading to EOF instead of exiting early. At these sizes that costs nothing. Also hardened the call form it depended on. has_heading passed `-` to mean stdin, but a `-` file operand is a convention rather than something every awk guarantees, and where it is taken literally the helper emits nothing and every heading looks absent. rendered_lines now forwards "$@", so a zero-argument call reaches awk as a zero-operand call -- stdin in every awk. Both defects produce the identical symptom; both are closed. The existing --check-bump pass test used a three-line changelog, which is why this shipped: with the heading on line 3 there is nothing left to write after the matcher stops, so neither defect can fire. Added a >64KiB fixture with the matched heading first, a cross-check that --check (which reaches rendered_lines by path, not stdin) agrees on the same file, and a direct probe that rendered_lines with no argument reads stdin. Co-authored-by: Claude Opus 5 (1M context) --- scripts/check-changelog-parity.sh | 30 +++++++++++++--- scripts/check-changelog-parity.test.sh | 48 ++++++++++++++++++++++++++ 2 files changed, 74 insertions(+), 4 deletions(-) diff --git a/scripts/check-changelog-parity.sh b/scripts/check-changelog-parity.sh index 4d66c2d1e..93e00fce7 100755 --- a/scripts/check-changelog-parity.sh +++ b/scripts/check-changelog-parity.sh @@ -139,7 +139,15 @@ version_sort_key() { # content. Comment markers inside fenced code are content; fence markers inside a # comment are suppressed. A line that BEGINS inside a comment is suppressed whole # even when the comment closes on it: what follows `-->` can never be a -# column-one heading anyway. Reads $1, or stdin when $1 is `-`. +# column-one heading anyway. +# +# Reads the file named by $1, or stdin when called with NO argument. It used to +# document `-` as the stdin form and pass "$1" through unconditionally. That is +# not portable: a `-` file operand meaning stdin is a convention, not something +# every awk honours, and when it is taken literally the helper emits nothing and +# every caller silently concludes the file has no headings. Forwarding "$@" +# instead lets a zero-argument call reach awk as a zero-operand call, which +# reads stdin in every awk there is. rendered_lines() { awk ' { @@ -181,7 +189,7 @@ rendered_lines() { rem = substr(rem, r + 3) } } - ' "$1" + ' "$@" } # The version headings a changelog declares, in file order. Every heading form @@ -429,10 +437,24 @@ for manifest in "${manifests[@]}"; do # — or falsely pre-exists — the release entry, and SemVer metacharacters # (1.0.1+build.1) never leak into a regex. A same-line "" can # never match anyway (the heading is not at column one). + # + # Two things here are deliberate and must not be "optimized" back: + # + # 1. rendered_lines is called with NO argument, not `-`. See its comment; a + # literal `-` operand is not portably stdin. + # 2. The matcher does NOT `exit` on the first hit. This runs under + # `set -o pipefail` (line 63), so an early exit closes the pipe while + # rendered_lines is still writing, rendered_lines dies of SIGPIPE (141), + # and pipefail makes 141 the status of the whole pipeline — turning a + # FOUND heading into "no entry at head". Whether the writer has already + # finished depends on how much of the changelog fits in the pipe buffer, + # so it passes on short changelogs and on some platforms and fails on + # others, which is exactly how it presented. Reading to EOF costs + # nothing at these sizes and removes the race. heading="## [${head_version}]" has_heading() { - rendered_lines - | awk -v h="$heading" ' - index($0, h) == 1 { found = 1; exit } + rendered_lines | awk -v h="$heading" ' + index($0, h) == 1 { found = 1 } END { exit !found } ' } diff --git a/scripts/check-changelog-parity.test.sh b/scripts/check-changelog-parity.test.sh index 3b0c691ca..834ddae13 100755 --- a/scripts/check-changelog-parity.test.sh +++ b/scripts/check-changelog-parity.test.sh @@ -217,6 +217,54 @@ git -C "$repo" add -A >/dev/null && git -C "$repo" commit -qm bump if (cd "$repo" && bash scripts/check-changelog-parity.sh --check-bump "$base" >/dev/null 2>&1); then ok "bump + '## [x.y.z]' entry passes --check-bump"; else fail "bump+entry wrongly failed"; fi rm -rf "$repo" +# REAL-WORLD SHAPE: the new entry at the TOP of a LONG changelog. The case above +# passes on a three-line file, which is why this class shipped undetected — with +# the heading on line 3 there is nothing left to write after the matcher stops, +# so neither of the two defects this guards against can fire: +# +# 1. has_heading fed rendered_lines a `-` operand for stdin, which is a +# convention rather than something every awk honours. Where it is taken as +# a literal filename the helper emits nothing and every heading looks absent. +# 2. The matcher exited on the first hit. Under `set -o pipefail` that closes +# the pipe mid-write, rendered_lines takes SIGPIPE (141), and pipefail +# promotes 141 to the pipeline's status — so a FOUND heading reports as +# "no entry at head". It only bites once the unread remainder outgrows the +# pipe buffer, i.e. on exactly the changelogs a long-lived plugin has. +# +# Keep this changelog comfortably over 64 KiB (the usual pipe capacity) and keep +# the matched heading FIRST; both are load-bearing. +repo="$(mk_repo)" +git_init "$repo" +mk_plugin "$repo" alpha 1.0.0 yes +git -C "$repo" add -A >/dev/null && git -C "$repo" commit -qm base +base="$(git -C "$repo" rev-parse HEAD)" +printf '{ "name": "alpha", "version": "1.1.0" }\n' >"$repo/plugins/alpha/.claude-plugin/plugin.json" +{ + printf '# Changelog\n\n## [1.1.0]\n\nthe entry under test\n\n' + i=900 + while ((i > 0)); do + printf '## [0.%d.0]\n\nan older release note long enough to push this file past the pipe buffer\n\n' "$i" + i=$((i - 1)) + done +} >"$repo/plugins/alpha/CHANGELOG.md" +size="$(wc -c <"$repo/plugins/alpha/CHANGELOG.md")" +((size > 65536)) || fail "fixture too small to exercise the pipe-buffer path: ${size} bytes" +git -C "$repo" add -A >/dev/null && git -C "$repo" commit -qm bump +if (cd "$repo" && bash scripts/check-changelog-parity.sh --check-bump "$base" >/dev/null 2>&1); then ok "a top-of-file entry in a >64KiB changelog passes --check-bump"; else fail "long changelog wrongly reported as UNDOCUMENTED BUMP"; fi +# The same file must stay readable by --check, which reaches rendered_lines by +# path rather than stdin — so a fix to one call form cannot break the other. +if (cd "$repo" && bash scripts/check-changelog-parity.sh --check >/dev/null 2>&1); then ok "--check agrees with --check-bump on a long changelog"; else fail "--check disagreed on the long changelog"; fi +rm -rf "$repo" + +# rendered_lines with NO argument must read stdin — has_heading depends on it, +# and a `-` operand must not creep back in. +probe="$(printf '# t\n\n## [9.9.9]\n' | bash -c ' + set -uo pipefail + eval "$(sed -n "/^rendered_lines()/,/^}/p" "$1")" + rendered_lines | grep -c "^## \[9\.9\.9\]$" +' _ "$SCRIPT" 2>/dev/null || true)" +if [[ "$probe" == "1" ]]; then ok "rendered_lines with no argument reads stdin"; else fail "rendered_lines does not read stdin when called with no argument (got '${probe}')"; fi + # SYNTHETIC MALFORMED ENTRY: version present but as an UNBRACKETED heading # (## 1.1.0) -> FORMAT error naming the found heading, NOT "UNDOCUMENTED BUMP". repo="$(mk_repo)" From 6f4f8324bda000d3fb6ae8201afabac2ab63e282 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 10 Aug 2026 13:37:17 -0400 Subject: [PATCH 5/5] fix(songwriting): correct the bridge function-2 row itself, not the note under it Review raised this three times and I kept answering it in prose beneath the table. form.md's function-2 "Effect" cell still read "Insert a non-matching unit between matching units" -- the bridge's-own-phrase-count framing this branch exists to reject -- with the correction sitting three lines below as an addendum. A table is the format readers scan, so the row was still handing out the wrong diagnosis to anyone who did not read past it. The row now carries the corrected claim: the SYSTEM changes size, shorter in verse/chorus and longer in verse/refrain and AABA. The paragraph below keeps only the explanation of why the direction differs. Co-authored-by: Claude Opus 5 (1M context) --- .../songwriting/context/pat-pattison/research/form.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/plugins/songwriting/context/pat-pattison/research/form.md b/plugins/songwriting/context/pat-pattison/research/form.md index 6c50208f8..d01b76283 100644 --- a/plugins/songwriting/context/pat-pattison/research/form.md +++ b/plugins/songwriting/context/pat-pattison/research/form.md @@ -538,12 +538,14 @@ gives a separate five-point account of what a bridge *is* — see | Function | Effect | When | |---|---|---| | 1. Break monotony | Disrupt the verse-chorus repetition | The form has run V/Ch twice and risks fatigue | -| 2. Create a different-size song system | Insert a non-matching unit between matching units | The song's symmetry needs interruption | +| 2. Create a different-size song system | Change the size of the final SYSTEM, not the bridge's own phrase count — shorter in verse/chorus, longer in verse/refrain and AABA | The song has run same-size systems and their symmetry needs interruption | | 3. Provide a new perspective | Shift POV, tense, or speaker | The chorus has stated; the bridge reframes | -Function 2 is about the **system's** size, not the bridge's own phrase count, -and "different" does not always mean "shorter" — in verse/chorus the final -system shrinks, in verse/refrain and AABA it grows. See [bridge](bridge.md). +Function 2's direction depends on what the bridge groups with: in verse/chorus a +short bridge shrinks the last system so the final chorus arrives early, while in +verse/refrain and AABA the bridge plus the final verse make a system *longer* +than the verse-only ones before it. Pat's word is **different**, not shorter. +See [bridge](bridge.md). A bridge that serves only one function may still work. A bridge that serves none should be cut — verse-chorus alone is enough.