@boopkit/cap-product-design 0.6.1 → 0.6.3

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.3",
   "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
 ---

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.