@boopkit/cap-product-design 0.6.4 → 0.6.6

package/capability.json

@@ -11,7 +11,9 @@
     "boop-product-design-feature-requirements",
     "boop-product-design-reference-integration",
     "boop-product-design-thought-partnership",
-    "boop-writing-technical-prose"
+    "boop-writing-technical-prose",
+    "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.4",
+  "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

@@ -0,0 +1,108 @@
+---
+name: boop-writing-documents
+description: "When you need to write a document someone will read cold and act on — a proposal, strategy memo, analysis, recommendation, or status write-up — and want the discipline of the Amazon six-pager: narrative prose, a declared length budget, claims that carry their evidence, and the hard questions answered inside the document."
+metadata:
+  category: writing
+---
+
+# Writing Documents
+
+When you need to write a document a colleague will read on their own and then act on, write it as narrative prose under a length limit you set before you start, using the discipline the Amazon six-page memo enforces — even when the six-pager's literal sections are the wrong shape for the job.
+
+## Goal
+
+**A document has to carry a reader from not knowing to being able to act, in one silent read, with the author unavailable to explain anything.** That is the standard the six-pager is built around: the meeting opens with everyone reading the memo in silence, so the document is the entire presentation. There is no narration holding it together and no chance to answer a question in the moment.
+
+Two beliefs do most of the work, and both are about the writer rather than the reader.
+
+**Prose in full sentences is a thinking instrument.** A bullet list lets you set two claims side by side without ever stating how the first supports the second. That relationship *is* the argument, and in a list nobody has to write it down — not the reader, and more importantly not the writer. A paragraph forces the connecting sentence to exist, and the moment you find you cannot write that sentence, you have discovered you do not yet have an argument. This is the facet of the six-pager most worth keeping everywhere. It is why the format bans slides, and it is why a good memo takes several drafts rather than one.
+
+**A length budget is what makes a document say something.** Selection only happens against a constraint. With no limit, every true sentence survives and the reader receives a survey instead of a position. Six pages is Amazon's number and there is nothing special about six. Pick a number before you write — half a page, two pages, six — and treat it as fixed. When the material will not fit, cut content: decide what this reader does not need. Do not reclaim space by compressing paragraphs into bullets, which trades the argument for the appearance of one.
+
+### Write so the reader needs no pre-existing context
+
+**Write so a reader, whether a fresh agent or a human, can use the artifact without much pre-existing context.** The reader was not in the planning session and did not grow up with the project's internal vocabulary. They should be able to read the prose and understand it. When that constraint is met the writing is doing its job. When it is not — when the reader has to translate from shorthand into normal language before they can start — the writing is spending the reader's attention on decoding instead of on the work.
+
+Two properties do most of that work:
+
+- **Words both common and specific.** Use ordinary words for ordinary meaning and the real technical term when the subject is technical. These pull in the same direction: `column`, `foreign key`, `parameter`, `index` are common *and* exact, and a sentence built from them is readable and precise at once. The failure is a word that is neither — vague but technical-sounding, or coined on the spot. If a word feels precise but you cannot point to where the industry defined it, you have reached for the feeling of precision instead of the thing.
+- **Context local to the paragraph.** Each paragraph carries what it needs to be understood on its own. Do not refer back to a label, abbreviation, or shorthand defined earlier and leave the reader to reassemble it. Restate the thing in a few words at the point of use, even when you defined it two paragraphs above: it costs a clause and saves a lookup. This matters most in summaries and conclusions, which is exactly where compression is most tempting, because by then the content feels settled to the writer and is still new to the reader.
+
+Apply both hardest when summarizing, concluding, or recommending. Those are the passages a reader is most likely to read alone, out of order, or months later. For the full treatment of this, including the anti-patterns, see [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md).
+
+## What carries over from the six-pager
+
+These apply to any document, whatever its sections.
+
+1. **A purpose line at the top that names the reader and their job.** Not a line describing the document's subject. "For the engineer decomposing this into tasks: what changes, in what order, and which decisions are already settled" names a reader and a job. "What we need to build" only describes the document. That line is the only place where the question *who reads this, and what must they be able to do afterwards* leaves a visible trace, and once it exists everything below it has a standard to be judged against.
+2. **Narrative prose in the body.** Tables and lists are fine where the content is genuinely tabular or is a genuine set of parallel items — five vendors, a schedule, a sequence of steps. The rule is against using list formatting to skip the reasoning, not against lists.
+3. **Claims carry their evidence where they are made.** A number appears with where it came from. "Three of the eleven agents we interviewed" rather than "most agents." When you do not have the number, write the sentence without one and say what would have to be measured to get it. An invented figure fails worse than a missing one, because it survives into other people's decisions and cannot be traced back.
+4. **What the record shows, kept separate from what you infer from it.** Mark the difference in the prose — this is what we observed, this is what we take it to mean, this is what we are assuming. A document that reads at a uniform level of confidence tells the reader that everything in it is equally sourced, and it never is.
+5. **The questions that hurt, asked and answered in the document.** The six-pager's FAQ section exists so the author cannot choose which objections get raised. Write down the strongest thing an informed skeptic would say against the recommendation, and answer it — genuinely, or by conceding the point and saying what it costs. An FAQ made only of questions you are comfortable with is advertising.
+6. **The body holds the argument, the appendix holds the detail.** Supporting data, derivations, transcripts, and full tables go behind the main text so the read stays continuous. No claim in the body may depend on the reader opening the appendix.
+7. **Revision is mostly deletion, and delivering is a separate act from drafting.** The draft is where you work out what is true, in whatever shape that takes. Delivery is where you name the reader, read the draft back as that reader, and remove whatever does not serve their job however good it sounds. "Does this read well" is not a usable standard, because prose that argues a case or reaches for a vivid image is exactly what good writing feels like from the inside. "After reading this, can they do the thing?" is a question you can actually answer.
+
+## Choosing the document's shape
+
+The six-pager assumes a decision is being asked for. When the document is not asking for one, forcing its sections produces hollow headings — *Alternatives Considered* with nothing real under it, *The Ask* that asks for nothing — and a hollow section is worse than a missing one because it looks answered.
+
+Match the spine to the job:
+
+| The document's job | Spine |
+| --- | --- |
+| Get a decision made | Context, the problem, approaches considered, the recommendation, what it costs, what you need from the reader |
+| Report an analysis or finding | The question, the answer, the evidence, what the evidence does not settle |
+| Propose something to build | Working backwards: the customer, what changes for them once it exists, then the FAQ |
+| Report status | What changed, what it means for the goal, what is stuck, what happens next |
+| Record a decision already made | What was decided, what was true when we decided it, what would make us revisit |
+
+In each of these the discipline above still applies in full. Only the section list changes.
+
+## Before writing, three lines
+
+Write these at the top of the draft:
+
+- **Reader** — who specifically, and what they already know.
+- **Their job** — what they must be able to do when they finish.
+- **Budget** — the page or word count, fixed now.
+
+The first two usually combine into the purpose line and stay. The budget line goes at delivery.
+
+## Revision passes
+
+Run these separately and name which one you are in. They substitute for each other otherwise: a reviewer who sets out to check the phrasing, finds four factual errors, and stops has run a content review while believing the writing was reviewed. In a phrasing pass, a factual error you happen to notice gets written down and set aside rather than reported as the outcome.
+
+1. **Evidence.** Every number, quote, date, and attribution checked against its source. Downgrade anything that turns out to be inference rather than record.
+2. **Objection.** Read it as the person with the most to lose if the recommendation is adopted. Whatever they would say first belongs in the document.
+3. **Deletion.** Cut to the budget. Sentences that carry only emphasis or build-up go first.
+4. **Phrasing.** Read each sentence as if explaining it to a colleague who was not in the planning session. Where they would stop and ask what a term means, rewrite.
+
+When a reader points at one fault, treat it as an example rather than an inventory. Re-run the whole standard instead of sweeping only the class that was named — fixing every instance of the named pattern and stopping leaves everything else in place, and reads as thorough precisely because the named class is now clean.
+
+## Failure modes
+
+- **A grid of bullets that asserts without connecting.** Nested lists and three-column tables look organized and can contain no argument at all. If the reasoning between two items is never written, it was never done.
+- **Symmetric coverage.** Every section the same length and every option given equal treatment, because balance resembles rigor. Real documents are lopsided: the thing that matters gets most of the pages.
+- **Unsourced intensifiers.** "Significantly improves", "industry-leading", "most teams", "widely regarded". Each is a claim with the evidence removed. Either source it or drop the intensifier.
+- **Fabricated specificity.** A percentage, a citation, or a dollar figure invented to satisfy the rule that claims carry evidence. The rule to attach evidence actively invites this, which is why it is named here: absence of a number is a reportable fact, and a wrong number is not.
+- **The recommendation withheld.** Options laid out with studied neutrality so the author is never wrong. When the document is asked to recommend, it contains a recommendation, in one sentence, early.
+- **Headings as empty containers.** *Background*, *Considerations*, *Next Steps* filled with whatever is generically true about the topic. A heading names something specific the section establishes.
+- **An introduction that describes the document.** "This document explores the various factors involved in…" is throat-clearing. Start with the situation or the finding.
+- **Length standing in for effort.** More pages read as more work and are usually less selection.
+- **A conclusion that restates the headings.** The last section either says what to do or does not exist.
+
+## Checklist
+
+- Does the first line name a reader and what they will be able to do?
+- Is it within the budget that was set before writing?
+- Does the argument survive in prose, with the connections between claims actually written down?
+- Does every number and quotation have a source, and is anything inferred marked as inferred?
+- Is the strongest objection in the document, answered?
+- If a recommendation was asked for, is it stated plainly and early?
+- Would someone who cannot ask a question get what they need from one silent read?
+
+## Related
+
+- [`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.