@boopkit/cap-product-design 0.6.5 → 0.6.6

package/capability.json

@@ -12,7 +12,8 @@
     "boop-product-design-reference-integration",
     "boop-product-design-thought-partnership",
     "boop-writing-technical-prose",
-    "boop-writing-documents"
+    "boop-writing-documents",
+    "boop-writing-semantic-line-breaks"
   ],
   "skill_migrations": {
     "boop-product-design-engineering-design": "design.engineering-design.skill.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-product-design",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Product design skills for AI agents",
   "files": [
     "skills/",

package/skills/boop-product-design-engineering-design/SKILL.md

@@ -201,4 +201,7 @@ For each row, the justification names *why this mechanism fits this job's shape*
 
 ### Why this matters
 
-Without an explicit interaction-shapes pass, the agent inherits whatever pattern the existing page already uses, justifies it post-hoc against whatever frame is available, and produces a design that converges on the existing shape regardless of how the jobs have changed. The pass forces a clean per-affordance decision and makes the design visible. It also makes the design checkable — a reviewer can read the affordance table and ask, for each row, *does this mechanism fit this job?*
+Without an explicit interaction-shapes pass, the agent inherits whatever pattern the existing page already uses, justifies it post-hoc against whatever frame is available, and produces a design that converges on the existing shape regardless of how the jobs have changed. The pass forces a clean per-affordance decision and makes the design visible. It also makes the design checkable — a reviewer can read the affordance table and ask, for each row, *does this mechanism fit this job?*
+## Related
+
+- [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — design docs live in `specs/`; break their lines semantically so edits diff cleanly.

package/skills/boop-product-design-feature-documentation/SKILL.md

@@ -8,4 +8,8 @@ metadata:
 - Identity the intended audience. For example, data engineers who may not have done this sort of exercise before.
 - Identify the audience's "group identity". For example, which company, team, or project they belong to.
 - Identify the activity to be explained. For example, designing or operating at scale.
-- Write up an introduction to {audience} that haven’t done this sort of {activity} before. This should be a gentle intro, {group identity} flavored, “this is going to be fun” toned, very precise engineering speak explanation of what is going to be in place for {activity}. Use “we” as needed. Provide as markdown.
+- Write up an introduction to {audience} that haven’t done this sort of {activity} before. This should be a gentle intro, {group identity} flavored, “this is going to be fun” toned, very precise engineering speak explanation of what is going to be in place for {activity}. Use “we” as needed. Provide as markdown.
+
+## Related
+
+- [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — when the documentation lands in a markdown file in the repo.

package/skills/boop-product-design-feature-requirements/SKILL.md

@@ -109,3 +109,7 @@ When writing a feature spec, work the following order. Each step depends on the
 8. **Success metrics** — per job, observable
 
 Steps 1–3 are where this skill earns its keep. Skipping them produces well-structured feature checklists with no design clarity downstream.
+
+## Related
+
+- [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — specs live in `specs/`; break their lines semantically so edits diff cleanly.

package/skills/boop-product-design-reference-integration/SKILL.md

@@ -48,3 +48,7 @@ After editing, verify:
 - **"See also" link dumps** — links should be inline where the concept is discussed, not in a footer list
 - **Copy-pasting from the spec** — specs use future tense and rationale; reference uses present tense and describes what is, not why it was chosen
 - **Leaving stale content** — if the feature changes existing behavior, update or remove the old description
+
+## Related
+
+- [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — `reference/` pages are edited far more often than they are written; semantic line breaks are what keep those edits reviewable.

package/skills/boop-writing-documents/SKILL.md

@@ -105,3 +105,4 @@ When a reader points at one fault, treat it as an example rather than an invento
 
 - [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md) — sentence-level standard and the full anti-pattern list; this skill inherits its goal.
 - [`boop-product-design-feature-requirements`](../boop-product-design-feature-requirements/SKILL.md) — when the document is a feature spec or PRD.
+- [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — line-break convention for the markdown source of the document.

package/skills/boop-writing-semantic-line-breaks/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: boop-writing-semantic-line-breaks
+description: "When you need to write or edit prose in a markdown file under version control — a spec, a reference page, a README, a skill — break lines at semantic boundaries rather than at a fixed column, so that edits produce readable diffs."
+metadata:
+  category: writing
+---
+
+# Semantic Line Breaks
+
+## Goal
+
+**A line break in a prose file is a diff tool, not a formatting preference.**
+
+Hard-wrapping at a fixed column puts the break wherever the word count happens to run out.
+Change one word early in a paragraph and every line after it reflows, so the diff shows a rewritten paragraph when what actually changed was an adjective.
+Nobody can review that.
+
+Semantic line breaks put the break where the *thought* breaks.
+An edit to a sentence then shows up as a one-line diff, a review comment lands on the claim it is about, and a reader scanning the source sees the shape of the argument before reading a word of it.
+
+The rendered output is identical either way.
+Markdown treats a single newline inside a paragraph as a space, so this is invisible to anyone reading the published page.
+It is purely a convenience for the people editing and reviewing the source.
+
+This follows the [Semantic Line Breaks specification](https://sembr.org/) (SemBr), with one deliberate deviation — see below.
+
+## The rules
+
+From the specification:
+
+- A break **MUST** come after a sentence ending in `.`, `!`, or `?`.
+- A break **SHOULD** come after an independent clause punctuated by a comma, semicolon, colon, or em dash.
+- A break **MAY** come after a dependent clause, to clarify structure.
+- A break is **RECOMMENDED** before a list, and **MAY** follow list items to group related entries.
+- A break **MUST NOT** fall inside a hyphenated word.
+- A break **MAY** come before or after a hyperlink, and before inline markup.
+
+Two rules govern all the others: the breaks **MUST NOT** change the rendered output, and they **SHOULD NOT** change the intended meaning.
+If a break makes a sentence read differently, put it somewhere else.
+
+### Our deviation: no maximum line length
+
+The specification recommends an 80-character maximum.
+**We do not follow that rule.**
+
+It is the one rule in the spec that works against the goal.
+In real prose most sentences run past 80 characters, often well past.
+An 80-column ceiling therefore forces a mid-sentence break in most sentences, and the leftover clause lands alone on a line as a fragment — which is precisely the arbitrary, non-semantic break the convention exists to avoid.
+The ceiling only ever served people reading source in an 80-column terminal, and every editor we use soft-wraps.
+
+So: let a line be as long as the thought it carries.
+
+## Deciding where the break goes
+
+**One sentence per line is the default.**
+A sentence is the unit of thought; a clause usually is not.
+
+Break *within* a sentence only when both of these are true:
+
+1. The sentence is long — past roughly 100 characters of visible text.
+2. It contains two or more genuinely **independent** claims, joined by a semicolon, colon, em dash, or coordinating conjunction.
+
+A trailing dependent clause is not a second claim.
+"A request that arrives after the cache has expired still succeeds, because the loader falls back to the origin" stays on one line: the `because` clause cannot stand alone, so splitting it strands a fragment.
+
+Short sentences always stay whole, however tempting the parallel.
+"A read hits the cache; a write goes to the origin" is under fifty characters, and the contrast *is* the thought — breaking it in half makes two half-thoughts.
+
+Count visible text, not markup.
+A line carrying a long markdown link is shorter than it looks; judge it by what the reader sees.
+
+## Where this applies
+
+**Use semantic line breaks in:**
+
+- `specs/` — design docs and specifications
+- `reference/` — the current-state documentation
+- `skills/*/SKILL.md` — including this one
+- `README.md`, `AGENTS.md`, `CLAUDE.md`, and any other prose markdown at the root
+
+**Do not use them in:**
+
+- **Markdown whose body is consumed as raw text rather than rendered** — a file sent to a model as a prompt, used as a template, or otherwise read verbatim, where the newlines survive into the payload.
+  A line break there changes the string, not just the diff.
+  Write those bodies as ordinary paragraphs.
+- **bd issue bodies.**
+  The payoff for semantic line breaks is a line-level diff, and an issue description is stored in the Dolt database and exported to `.beads/issues.jsonl` as a single JSON string — there is no line-level diff to improve.
+  `bd show` also re-wraps descriptions to the terminal width, keeping only blank-line paragraph breaks.
+  Write issue bodies as paragraphs separated by blank lines.
+- **Chat responses.** Nothing is being diffed. Write normally.
+- **Code and inline comments.** Follow the surrounding code's conventions.
+- **Commit messages.** The subject and body conventions in [`boop-coding-commit-changes`](../../../cap-coding/skills/boop-coding-commit-changes/SKILL.md) already govern these.
+
+## Editing a file that is not yet broken this way
+
+Do not reflow a whole file as a drive-by change.
+It buries the edit you actually came to make inside a diff that touches every line.
+
+Apply semantic breaks to the paragraphs you are already rewriting and leave the rest alone.
+A whole-file reflow is fine, but it belongs in its own commit with nothing else in it.
+
+When you do reflow a file, verify that you changed only whitespace: split both versions into blank-line-separated blocks, normalize the whitespace inside each block, and compare.
+Every block should match.
+
+## Example
+
+Hard-wrapped at 90 columns:
+
+```
+When a request comes in, resolve the config once at the top of the handler and pass it down.
+Reading it again deeper in the call stack re-parses the file and can pick up a different value
+mid-request; resolving once keeps the whole request consistent.
+```
+
+The same text with semantic line breaks:
+
+```
+When a request comes in, resolve the config once at the top of the handler and pass it down.
+Reading it again deeper in the call stack re-parses the file and can pick up a different value mid-request; resolving once keeps the whole request consistent.
+```
+
+One sentence per line.
+The second sentence keeps its semicolon clause on the same line because, long as it is, the two halves are one continuous point.
+Changing "at the top of the handler" to "at the entry point" now touches exactly one line.
+
+## Related
+
+- [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md) — how to choose the words; this skill only covers where to end the line.
+- [`boop-writing-documents`](../boop-writing-documents/SKILL.md) — longer-form document structure.

package/skills/boop-writing-technical-prose/SKILL.md

@@ -140,3 +140,4 @@ The first version compresses meaning into 60 words of jargon. The second uses ab
 - `boop-project-mgmt-beads-planning` — its "self-contained briefing" rule for issue bodies leans on the patterns described here.
 - `boop-product-design-engineering-design` — when writing spec prose. Specs are usually fine, but when they drift the same anti-patterns apply.
 - `boop-coding-review-changes` — when writing review summaries that follow-up agents will read.
+- [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — where to end the line in a markdown file. Word choice is this skill; line breaks are that one.