@boopkit/cap-product-design 0.6.1 → 0.6.4

package/capability.json

@@ -10,6 +10,7 @@
     "boop-product-design-feature-documentation",
     "boop-product-design-feature-requirements",
     "boop-product-design-reference-integration",
+    "boop-product-design-thought-partnership",
     "boop-writing-technical-prose"
   ],
   "skill_migrations": {

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: boop-product-design-engineering-design
-description: "When you need to design a feature or system and communicate the technical decisions. For UI features, includes a per-affordance interaction-shapes pass that derives page/surface count from job-anchored mechanism choices rather than asserting it up front."
+description: "When you need to design a feature or system and communicate the technical decisions — including when you frame the task as writing a design doc, drafting the technical or engineering section of a spec, deciding the architecture, or choosing how to build something. Reaching for an existing design to imitate its structure is not a substitute for the method. For UI features, includes a per-affordance interaction-shapes pass that derives page/surface count from job-anchored mechanism choices rather than asserting it up front."
 metadata:
   category: design
 ---
@@ -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-product-design-feature-documentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: boop-product-design-feature-documentation
-description: "When you need to document a complex feature, function or system"
+description: "When you need to document a complex feature, function, or system — including when you frame the task as 'write the docs', 'write a README', 'write up how X works', or 'explain this for the next reader who picks it up cold'."
 metadata:
   category: reqs
 ---

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

@@ -1,6 +1,6 @@
 ---
 name: boop-product-design-feature-requirements
-description: "When you need to define what a feature should accomplish before designing how to build it. Start with the user's jobs to be done, in frequency order; take and defend a stance; then derive goals, non-goals, and success metrics."
+description: "When you need to write a feature spec, draft a spec document, or turn a brief or vague directive into requirements — i.e. define what a feature should accomplish before designing how to build it. This fires even when you frame the task to yourself as just 'writing a spec' or 'matching the house spec format': reading an existing spec to imitate its shape is not a substitute for the method, and the more competent you feel at the raw task the more this applies. Start with the user's jobs to be done, in frequency order; take and defend a stance; then derive goals, non-goals, and success metrics."
 metadata:
   category: reqs
 ---

package/skills/boop-product-design-thought-partnership/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: boop-product-design-thought-partnership
+description: "When the user wants to think out loud through a design — a feature, a capability, a strategic direction — be a thought partner, not an implementer: hold the conversation at user-and-value altitude, honor uncertainty with hypotheses rather than pretend-decisions, and keep software-shaped concerns downstream of the user's lived problems."
+metadata:
+  category: design
+---
+
+# Design thought partnership
+
+## Goal
+
+When the user wants to think out loud through a design — a feature, a capability, a strategic direction — be a thought partner, not an implementer. Hold the conversation at the altitude the user is at, which is almost always at user-and-value altitude rather than at data-model and code-structure altitude. Honor uncertainty by committing to hypotheses, not pretending to decisions. When the discussion gets captured in an artifact, capture it in a way that does not distort the user's framing through software-shaped concerns.
+
+## When to use this skill
+
+- The user opens a design conversation about a feature, a capability, or a strategic direction.
+- The user asks gap-finding questions like "what is missing," "is the schema solid," "what are we not seeing yet."
+- You are about to draft a feature requirements doc, an engineering design doc, or any related artifact from a discussion.
+- You catch yourself drafting in data-model or code-structure shape when the discussion is at user level.
+
+## When this skill does not apply
+
+- The user is asking a concrete implementation question. They want you in the code, not in the design.
+- The discussion has already converged on a specific implementation approach and the user wants help executing it.
+
+## Core principles
+
+### 1. User altitude over system altitude
+
+The dominant failure mode is reaching for the data model, the code structure, or the migration plan when the user is still figuring out what they need to deliver. Resist the pull. Start at user altitude — who is the user, what is their lived problem, what does value look like to them — and stay there until the design at that level is settled.
+
+Implementation concerns (fields, actor enums, migration paths, idempotency, ripple effects) are real and worth raising. They are also downstream. Group them separately from the user-altitude concerns. When in doubt, ask "would the user describe this concern?" — if no, it is downstream. Foreground the user-shaped questions; file the software-shaped questions in a parking lot.
+
+### 2. Hypothesis over commitment in discovery mode
+
+When the future is genuinely unknown, the spec must not pretend it is known. Do not write "the spec should name how X happens" when you do not know how X happens — that asks the spec to commit to a decision the team has not figured out yet, and it dresses up speculation as a decision.
+
+The right move: pick the simplest informed hypothesis, mark it explicitly as a hypothesis (not a decision), and ensure it is easy to change. The language follows: "the v1 stance is X; we will learn from observation what to do next." A hypothesis you are willing to discard is more honest than a decision dressed up as one.
+
+The signal that prose has drifted into pretend-certainty: phrases like *"the spec should name how X happens,"* *"decide between A and B,"* *"pick the right model for Z"* — when none of those are answerable yet from anything we know today. The fix is to name the design space, name the hypothesis, and move on.
+
+### 3. Lived problems before invented problems
+
+Software has its own invented problems — idempotency, ripple effects across enums, migration windows, schema joins, actor branches. These are real, but they fall out of solving the user's actual problem. Do not lead with them. Do not let them shape the requirements conversation. Do not let them become the spine of a spec.
+
+The user's lived problems are the source. What is the user actually losing time over? What relationship are they protecting? What decision do they want to make in five seconds? Those are the questions that determine what gets built. The software-shaped questions answer themselves once the user-shaped questions are answered.
+
+### 4. The translation test still applies
+
+When the discussion gets captured into a spec or a doc, run the translation test from [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md). Specs drift into agent-shorthand as easily as anything else. Full sentences, no abstract noun stacks, no telegraphic shortcuts. A fresh reader must be able to act on the spec cold.
+
+## Working pattern
+
+When the user opens a design conversation:
+
+1. **Listen for the user.** Who are they? What is their problem? What does value look like to them? If the user has not named these yet, ask before reasoning about anything else.
+2. **Honor their framing.** They have context you do not. Take their sketch and build on it; do not rewrite from scratch unless asked.
+3. **Surface gaps at the level the conversation is at.** If they are at user altitude, raise user-altitude gaps. If they are at design altitude, raise design gaps. Do not pivot down to implementation unprompted.
+4. **Separate concerns explicitly.** When implementation concerns do come up, file them separately: "here is the user-level concern; here is the software-shaped question that follows from it." Let the user choose what to engage with.
+5. **In discovery, ship hypotheses.** When the right answer would require foresight nobody has, name the hypothesis, mark it as a hypothesis, and keep it easy to change.
+
+## Anti-patterns
+
+- **Pulling toward the code.** "The actor enum has to change, and that touches X surfaces" when the user wanted to talk about what their user experiences.
+- **Pretending to certainty.** "The spec should commit to X model for Y" when X is one of three plausible answers and there is no signal yet about which is right.
+- **Solving software problems the user does not have.** Idempotency, replay safety, migration windows — name them as downstream engineering concerns, do not present them as design decisions the user has a stake in.
+- **Rewriting a sketch instead of building on it.** If the user hands you four bullet points of design framing, build on those four bullets. Do not replace them with your own architecture and call that "synthesis."
+- **Asking for a decision the team cannot make yet.** A spec that says "decide A vs B" with no signal for choosing is asking the team to guess. A spec that says "the v1 hypothesis is A; if observation shows B is better, swap" honors what is actually known.
+
+## Related
+
+- [`boop-product-design-feature-requirements`](../boop-product-design-feature-requirements/SKILL.md) — the artifact-shape skill for feature reqs (jobs-to-be-done framing, stance, non-goals). This skill is about the *conversation* that produces a feature reqs doc; that skill is about what the doc itself looks like.
+- [`boop-product-design-engineering-design`](../boop-product-design-engineering-design/SKILL.md) — the artifact-shape skill for engineering design docs. Same relationship.
+- [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md) — apply when capturing the conversation into any artifact. Specs drift into shorthand as easily as anything else.
+- [`boop-project-mgmt-beads-planning`](../../../cap-project-mgmt/skills/boop-project-mgmt-beads-planning/SKILL.md) — when the conversation produces a bd issue, the issue body should follow the goal/approach/context shape described there for non-trivial work. The same hypothesis-not-commitment discipline applies to issue bodies as it does to spec prose.

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: