From d53792f41276c833f4ec12dc9e578d98673d7dea Mon Sep 17 00:00:00 2001 From: Michael Scott Asato Cuthbert Date: Thu, 27 Aug 2026 18:32:44 -1000 Subject: [PATCH 1/3] Add a prose section to the writing-docs skill Length was covered; voice was not. Adds rules for examples drawn from real music, leading with the verb, varying sentence length, cutting throat-clearing, and treating the house's dry humor as style rather than slippage. Shortens the skill description from 55 words to 34 -- it loads every session. AI-assisted (Claude) --- .agents/skills/writing-docs/SKILL.md | 31 +++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/.agents/skills/writing-docs/SKILL.md b/.agents/skills/writing-docs/SKILL.md index 345b2b150..bf6776ad5 100644 --- a/.agents/skills/writing-docs/SKILL.md +++ b/.agents/skills/writing-docs/SKILL.md @@ -1,11 +1,9 @@ --- name: writing-docs description: >- - House style for docstrings, code comments, and `Changed in`/`New in` version - markers in music21. Use whenever you write or edit a docstring or comment, add - a version marker, or decide where a bug fix's test belongs. Covers the length - target, the rule against narrating bugs you just fixed, and why regression - cases go in unittests rather than doctests. + House style for music21 prose: docstrings, comments, and `Changed in`/`New in` + markers. Read before writing any of them. Sets the length target, the voice, + and where a bug fix's test belongs. --- # Writing docs and comments @@ -16,6 +14,29 @@ Aim for about 40% of the length an LLM writes by default. Cut qualifiers, restatements, and the sentence that explains the sentence before it. A comment earning its place says something the code cannot. +## Prose + +Assume the reader is skimming and looking for an excuse to stop. Give them +something to catch on. + +**Examples are music.** `key.KeySignature(-3)` is E-flat major, so say E-flat +major. Reach into the corpus rather than inventing `foo`: `bwv66.6` and +`luca/gloria` are in hundreds of docstrings because a reader can hear them. + +**Lead with the thing itself.** "Returns the pitches sounding at an offset," not +"This method can be used to obtain the pitches that are sounding." + +**Vary sentence length.** Three medium declaratives in a row is where the eye +slides off the page. A short one lands. + +**Cut throat-clearing.** "It is important to note that," "Note that in general," +"This allows the user to." Start at the verb. + +**Personality is house style, not a lapse.** `Cannot determine sharps for +quarter-tone keys! silly!` and "it'd wig me out if I ever didn't see them in +reverse alphabetical order" are both shipping music21. Dry, specific, short. A +joke needing a second sentence to land is one sentence too long. + ## Say what is, not what was or what not to do Describe current behavior. Do not narrate the bug you just fixed, the old From 7e7a2a640bd82cfd2e31b3c67306144bc4215a19 Mon Sep 17 00:00:00 2001 From: Michael Scott Asato Cuthbert Date: Fri, 28 Aug 2026 10:41:51 -1000 Subject: [PATCH 2/3] Merge master into writing-docs-prose; drop rules master now covers Master's new "Examples" section already says pick examples musicians care about and that dull docs get closed, so this branch's versions of those go. What survives is the four rules master does not state: lead with the verb, vary sentence length, cut throat-clearing, and keep a joke to one sentence. AI-assisted (Claude) --- .agents/skills/writing-docs/SKILL.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/.agents/skills/writing-docs/SKILL.md b/.agents/skills/writing-docs/SKILL.md index 33b6afe57..41d4e664a 100644 --- a/.agents/skills/writing-docs/SKILL.md +++ b/.agents/skills/writing-docs/SKILL.md @@ -16,13 +16,6 @@ earning its place says something the code cannot. ## Prose -Assume the reader is skimming and looking for an excuse to stop. Give them -something to catch on. - -**Examples are music.** `key.KeySignature(-3)` is E-flat major, so say E-flat -major. Reach into the corpus rather than inventing `foo`: `bwv66.6` and -`luca/gloria` are in hundreds of docstrings because a reader can hear them. - **Lead with the thing itself.** "Returns the pitches sounding at an offset," not "This method can be used to obtain the pitches that are sounding." @@ -32,10 +25,10 @@ slides off the page. A short one lands. **Cut throat-clearing.** "It is important to note that," "Note that in general," "This allows the user to." Start at the verb. -**Personality is house style, not a lapse.** `Cannot determine sharps for -quarter-tone keys! silly!` and "it'd wig me out if I ever didn't see them in -reverse alphabetical order" are both shipping music21. Dry, specific, short. A -joke needing a second sentence to land is one sentence too long. +**Humor is house style, not a lapse.** `Cannot determine sharps for quarter-tone +keys! silly!` and "it'd wig me out if I ever didn't see them in reverse +alphabetical order" are both shipping music21. A joke needing a second sentence +to land is one sentence too long. ## Say what is, not what was or what not to do From 2466fb1759f5ffcdc6165f7d4798ec5511f0a799 Mon Sep 17 00:00:00 2001 From: Michael Scott Asato Cuthbert Date: Fri, 28 Aug 2026 10:46:42 -1000 Subject: [PATCH 3/3] Fold the prose rules into the existing sections No separate Prose heading: lead-with-the-verb joins Examples, sentence length, throat-clearing and joke length join Writing and Comment style. AI-assisted (Claude) --- .agents/skills/writing-docs/SKILL.md | 21 +++++---------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/.agents/skills/writing-docs/SKILL.md b/.agents/skills/writing-docs/SKILL.md index 41d4e664a..0e393cfcc 100644 --- a/.agents/skills/writing-docs/SKILL.md +++ b/.agents/skills/writing-docs/SKILL.md @@ -14,22 +14,6 @@ Aim for about 40% of the length an LLM writes by default. Cut qualifiers, restatements, and the sentence that explains the sentence before it. A comment earning its place says something the code cannot. -## Prose - -**Lead with the thing itself.** "Returns the pitches sounding at an offset," not -"This method can be used to obtain the pitches that are sounding." - -**Vary sentence length.** Three medium declaratives in a row is where the eye -slides off the page. A short one lands. - -**Cut throat-clearing.** "It is important to note that," "Note that in general," -"This allows the user to." Start at the verb. - -**Humor is house style, not a lapse.** `Cannot determine sharps for quarter-tone -keys! silly!` and "it'd wig me out if I ever didn't see them in reverse -alphabetical order" are both shipping music21. A joke needing a second sentence -to land is one sentence too long. - ## Say what is, not what was or what not to do Describe current behavior. Do not narrate the bug you just fixed, the old @@ -112,6 +96,9 @@ scramble "Chaminade", not "puppy". If you cannot think of a reason a musician wo Describe what a parameter is and does in English if it is not obvious; type alone is not documentation. +Lead with the thing itself: "Returns the pitches sounding at an offset," not "This method +can be used to obtain the pitches that are sounding." + No dull repetition in docs. A bit of humor is welcome in docs; the docs are written for humans who will close the window if they are dull. If seven methods do essentially the same thing, give extensive docs the first time and then later methods can refer back to the first method. Don't repeat the same docs over and over. @@ -153,5 +140,7 @@ comments in shipping code, not to tests. - When wording is dictated to the agent to substitute for original wording, use it. Do not add parentheticals. Only fix obvious typos. - No weapon-metaphors or overly militaristic language. Avoid "blast radius", "rearm", "landmine", "detonate" in issues/PR/code. Trigger or fire events is so commonly used that they're okay. +- Vary sentence length; three medium declaratives in a row is where the eye slides off the page. Cut throat-clearing — "It is important to note that", "Note that in general" — and start at the verb. +- A joke needing a second sentence to land is one sentence too long. `Cannot determine sharps for quarter-tone keys! silly!` is the register.