Bullet style — a writing style guide for technical bulleted critique

SKILL.md

Error in user YAML: (<unknown>): mapping values are not allowed in this context at line 2 column 279

---
name: bullet-style
description: Write tight, parallel-structured bullets for technical problem statements, RFC critique sections, GitHub discussion intros, and design doc analysis. Use when drafting or editing prose where bullets describe how a system behaves and why it's problematic. Triggers on: problem statement, RFC, design doc critique, discussion intro, bulleted analysis, "what's wrong with X."
---

Bullet style

A distilled style guide for technical bulleted critique — problem statements, RFC sections, GitHub discussion intros, anything where a bulleted list describes how a system works and why it's bad.

Markers in the rules below: ✅ explicitly taught through edits; ⚠️ observed in the user's drafts and confirmed when surfaced.

Overall structure

1. Open with a nut graf that signposts the bullets. ⚠️ The opening sentence should preview what the list contains. "...in a way that is slow, breaks separation of concerns, and increases complexity and bugs" sets up four problem-themed bullets. Prior art: nut graf (journalism), Pyramid Principle (Minto).

Per-bullet structure

2. Top-level bullets are full sentences, not tagged fragments. ✅ (Sub-bullets may be fragments — they're explanatory beats, not sentences.)

• ✗ "Slow: computing the version walks Git tags, and gets worse as history grows."
• ✓ "Walks Git tags to compute the version, which is slow and gets worse as history grows."

3. Lead with the mechanism, follow with the consequence. ✅ The subject is what the system does; the judgment subordinates. Prior art: inverted pyramid at the sentence level.

• ✗ "Slow, because computing the version walks Git tags..."
• ✓ "Walks Git tags to compute the version, which is slow..."

4. Keep bullets verb-parallel. ⚠️ Every bullet in a list opens with a verb in the same tense.

• ✓ "Fetches... / Walks... / Injects... / Treats... / Accumulates..."

5. Vary the consequence-connector across bullets. ✅ Use whichever fits each bullet's natural shape: relative clause, embedded verb, participle, where-clause. Don't make them uniform. Prior art: sentence variety / variatio.

• Relative clause: "...which is slow and gets worse as history grows."
• Embedded verb: "...leaks project-specific details..."
• Participle: "...making release-by-promotion awkward."
• Where-clause: "...where bugs are expensive and hard to test."

Verbs and compression

6. Strong verbs carry judgment. ⚠️ A loaded verb is an implicit claim — you don't need a separate evaluative clause. "Leaks" is the indictment. "Accumulates" implies passive buildup of cruft. Prior art: verb-driven prose (Roy Peter Clark), "use strong verbs" (Strunk & White).

7. Reach for hyphenated compound modifiers to compress. ⚠️ Where most writers use a relative clause, a compound modifier collapses it.

• ✗ "an area that is hard to test" / "bugs that break releases"
• ✓ "hard-to-test area" / "release-breaking bugs"

Formatting

8. No bold/italic when structure already carries the emphasis. ⚠️

• ✗ "...which is slow and gets worse..."
• ✓ "...which is slow and gets worse..."

9. Prefer "where" clauses over em-dash asides. ⚠️

• ✗ "in a hard-to-test area — release pipelines — causing release-breaking bugs."
• ✓ "in the release pipeline, where bugs are expensive and hard to test."

Content discipline

10. Stay faithful to the source. Don't reach for a vivid verb that overstates the mechanism. ✅

• Source: "Custom version injection adds complexity to the release pipeline, where bugs are expensive and hard to test."
• ✗ Overreach: "Threads custom version injection through the release pipeline..." ("threads" invents a mechanism that wasn't in the source)
• ✓ Final: "Accumulates complex custom code in the release pipeline, where bugs are expensive and hard to test."

11. Show the contrast; don't just name it. ⚠️ If something is "backwards" or "awkward," spell out what and why. Prior art: antithesis (rhetoric); show, don't tell.

• ✗ "Treats Git tags as release inputs, which is awkward."
• ✓ "Treats Git tags as release inputs, which is backwards: release-by-promotion should promote an already-validated commit, but the current flow requires a tag before the release exists."

12. Cut rhetorical flourishes. Replace with a direct technical consequence. ✅ Prior art: "omit needless words" (Strunk & White); "kill your darlings."

• ✗ "adds a network dependency on GitHub (need I say more)"
• ✓ "vulnerable to GitHub outages"