@boopkit/cap-product-design 0.6.3 → 0.6.5

package/capability.json

@@ -11,7 +11,8 @@
     "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"
   ],
   "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.3",
+  "version": "0.6.5",
   "description": "Product design skills for AI agents",
   "files": [
     "skills/",

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

@@ -33,6 +33,7 @@ For UI features, the same principle applies one level deeper: the hardest part i
 - **Non-Goals are as important as Goals** — they prevent scope creep and make trade-off reasoning explicit
 - **Alternatives section earns trust** — showing what you rejected (and why) is what separates a design from a description
 - **Details should be selective** — document the tricky parts and link to the rest; don't rewrite the code in prose
+- **Prefer grounded terminology** — name things with generally-accepted software-engineering and product terms, and reuse the codebase's own names for things that already exist; avoid coined metaphors and vague shorthand ("the spine," "the gate," "the fix"). A design doc full of private labels costs every reader a translation pass. See `boop-writing-technical-prose` (anti-pattern 13).
 - **Design docs live in `specs/`** — see [engineering-planning](./proj.engineering-planning.skill.md) for how designs become work plans
 
 ## For refactor specs: audit current state first
@@ -82,6 +83,21 @@ Refactor specs without a Current State section produce two failure modes that sh
 
 The audit converts both failure modes from review-time surprises into draft-time inputs. The cost is reading the existing code before drafting; it is small, and far smaller than the operator review effort spent catching what the spec failed to document.
 
+## State requirements as expectations, not as defects
+
+Write what the design should *do*, not what today gets wrong. This holds even when the defects are real and freshly observed — especially then, because a concrete defect list is the most tempting thing to lead with.
+
+A spec that opens with "the list shows only one owner, uses the wrong verb, and omits attribution" has three problems. The reader has to invert each item to work out what to build, which is work you could have done for them. The negatives become the thing they orient around, so the design converges on patching those three symptoms rather than serving the goal. And it under-specifies: "do not show only one owner" leaves open what *should* be shown, while "every owner appears, carrying its own state" answers it and covers the observed defect on the way past.
+
+The positive form is also more durable. Defects get fixed and the prose goes stale; the expectation stays true.
+
+- **Rewrite each defect as the expectation that supersedes it.** "The label says assigned when nothing is assigned" becomes "the wording matches what has actually happened."
+- **Keep the current state, but neutral and brief.** A refactor spec still owes the reader a Current State section (above) so the design composes with what shipped. One factual sentence — "this surface was built when an item had a single owner" — grounds the reader without setting a negative frame. A bulleted defect list does not.
+- **Put genuinely rejected approaches in Alternatives.** That is what the section is for, and it reads as judgement there rather than as grievance in the requirements.
+- **Never describe a mechanism that does not exist.** Naming a component the reader will go looking for — a service, a helper, a "pipeline" that was never built — is worse than being vague. Vagueness makes them investigate; false precision makes them hunt, or build a wrapper to match your description. If you are unsure a thing exists, say what should be true instead of naming the thing.
+
+This is a stronger form of the strawman rule: do not motivate a design against a wrong implementation, real or imagined. State the destination.
+
 ## Architecture Layering
 
 Well-designed systems separate concerns into layers with clear responsibilities and one-directional dependencies. The exact layers vary by project type, but the principle is universal:

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

@@ -0,0 +1,107 @@
+---
+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.

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

@@ -1,6 +1,6 @@
 ---
 name: boop-writing-technical-prose
-description: "When writing chat responses, bd issue bodies, or any artifact a fresh reader will pick up cold, write grammatical conversational English. Avoid the agent-shorthand patterns that compress meaning at the cost of legibility."
+description: "When writing chat responses, summaries, bd issue bodies, specifications, specs, or any artifact a fresh reader will pick up cold, write grammatical conversational English. Avoid the agent-shorthand patterns that compress meaning at the cost of legibility."
 metadata:
   category: writing
 ---
@@ -22,7 +22,7 @@ When that constraint is met, the writing is doing its job. When it is not — wh
 
 ## When this skill does not apply
 
-- **Specs:** spec prose tends to be careful already, because specs are written deliberately and read repeatedly. The patterns below still apply when a spec drifts into agent-shorthand, but specs are not the typical offender.
+- **Specs:** spec *grammar* tends to be careful, because specs are written deliberately and read repeatedly. But coined-metaphor terminology (anti-pattern 13) creeps into specs readily — a spec can be grammatically clean and still make the reader decode a private vocabulary of "spine," "gate," and "holder." That pattern applies to specs in particular; the others less often.
 - **Inline code comments:** comments live with the code and are read in that context, where the surrounding identifiers are visible.
 - **Commit messages:** short by convention; the patterns below mostly do not apply at this length.
 
@@ -98,6 +98,12 @@ Saying "three directions named" or "surfaced this" or "captured as" treats writi
 
 Sentences like "Looks reconciled, isn't." or "Mark blocked and stop." read as message-thread terseness rather than written prose. Use full sentences with subjects: "It looks reconciled but is not." "Mark the issue blocked and stop work on it."
 
+### 13. Coined metaphors and vague shorthand for a concept that already has a grounded name
+
+Reaching for an invented label — "the spine" for a workflow's ordered steps, "the gate" for an approval or acceptance step, "the holder" or "the latch" for a long-lived record or a one-time state change — or a vague pointer like "the fix" for a specific change, forces the reader to learn a private vocabulary for something that already has a generally-accepted software-engineering or product name. The coined term feels precise to the writer, who knows what it stands for; it reads as jargon to everyone else, and worst of all invents a synonym for a thing the codebase or the domain already names.
+
+**Fix.** Use the established term, or describe the thing plainly. "The workflow's ordered task sequence," not "the spine." "The result-acceptance step," not "the gate." "A long-lived support record," not "the holder." "This change," or the specific behaviour it names, not "the fix." When a project-specific term is genuinely load-bearing — an entity name, a named phase — define it in plain words on first use, then use it consistently. If the concept already has a name in the codebase or the product domain, use that name rather than minting a metaphor for it.
+
 ## bd issue bodies specifically
 
 bd issue bodies have a higher bar than chat responses because: