@boopkit/cap-product-design 0.6.3 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-product-design",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "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-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: