@boopkit/cap-product-design 0.3.1 → 0.6.1

package/README.md

@@ -12,10 +12,10 @@ A bundle of agent-facing skill files for requirements, design, feature docs, and
 
 Copied into `skills/` on install:
 
-- `reqs.feature-requirements.skill.md` — how to turn a brief or vague directive into real requirements: ask 3-5 focused trade-off questions, push back on ambiguity without interrogating, and know when enough clarity is enough to proceed.
-- `reqs.feature-documentation.skill.md` — how to write feature documentation aimed at a specific audience and activity, with the right tone and grounding for readers who haven't done this before.
-- `design.engineering-design.skill.md` — the engineering design doc structure (Goals, Non-Goals, Approach, Alternatives, Tradeoffs, Open Questions) with a stance: make the *decision* visible, not just the solution.
-- `docs.reference-integration.skill.md` — how to blend new knowledge into `reference/` after a feature lands, keeping it a living wiki of what the system actually is, not a pile of per-feature pages.
+- `boop-product-design-feature-requirements/SKILL.md` — how to turn a brief or vague directive into real requirements: ask 3-5 focused trade-off questions, push back on ambiguity without interrogating, and know when enough clarity is enough to proceed.
+- `boop-product-design-feature-documentation/SKILL.md` — how to write feature documentation aimed at a specific audience and activity, with the right tone and grounding for readers who haven't done this before.
+- `boop-product-design-engineering-design/SKILL.md` — the engineering design doc structure (Goals, Non-Goals, Approach, Alternatives, Tradeoffs, Open Questions) with a stance: make the *decision* visible, not just the solution.
+- `boop-product-design-reference-integration/SKILL.md` — how to blend new knowledge into `reference/` after a feature lands, keeping it a living wiki of what the system actually is, not a pile of per-feature pages.
 
 ## Requirements
 
@@ -33,10 +33,10 @@ Skills are meant to be read by AI agents, not humans (though humans are welcome)
 
 How agents find them depends on the harness:
 
-- Projects with a Claude Code `CLAUDE.md` typically instruct the agent to consult `skills/index.md` or the relevant `.skill.md` file before acting.
-- Harnesses with a native skill-discovery system (e.g. slash-command style skills) surface them by filename.
+- Projects with a Claude Code `CLAUDE.md` typically instruct the agent to list the `skills/` directory and read each folder's `SKILL.md` frontmatter before acting.
+- Harnesses with a native skill-discovery system (e.g. slash-command style skills) surface them by folder name.
 
-A typical flow: a founder gives the agent a two-sentence feature brief. The agent reads `reqs.feature-requirements.skill.md` and asks a few trade-off questions to fill the gaps. Once the shape is clear it reads `design.engineering-design.skill.md` and writes a design doc with an explicit Alternatives section. After the feature ships, it reads `docs.reference-integration.skill.md` and blends the new behaviour into the existing concept pages in `reference/` — not a new feature-specific page.
+A typical flow: a founder gives the agent a two-sentence feature brief. The agent reads `boop-product-design-feature-requirements/SKILL.md` and asks a few trade-off questions to fill the gaps. Once the shape is clear it reads `boop-product-design-engineering-design/SKILL.md` and writes a design doc with an explicit Alternatives section. After the feature ships, it reads `boop-product-design-reference-integration/SKILL.md` and blends the new behaviour into the existing concept pages in `reference/` — not a new feature-specific page.
 
 ## Added by
 

package/capability.json

@@ -5,5 +5,17 @@
   "dependencies": [],
   "devDependencies": [],
   "files": [],
-  "skills": ["design.engineering-design.skill.md", "reqs.feature-documentation.skill.md", "reqs.feature-requirements.skill.md"]
+  "skills": [
+    "boop-product-design-engineering-design",
+    "boop-product-design-feature-documentation",
+    "boop-product-design-feature-requirements",
+    "boop-product-design-reference-integration",
+    "boop-writing-technical-prose"
+  ],
+  "skill_migrations": {
+    "boop-product-design-engineering-design": "design.engineering-design.skill.md",
+    "boop-product-design-feature-documentation": "reqs.feature-documentation.skill.md",
+    "boop-product-design-feature-requirements": "reqs.feature-requirements.skill.md",
+    "boop-product-design-reference-integration": "docs.reference-integration.skill.md"
+  }
 }

package/package.json

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

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

@@ -0,0 +1,188 @@
+---
+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."
+metadata:
+  category: design
+---
+# Engineering Design
+
+## Goal
+**Make the decision visible, not just the solution.**
+
+The hardest part of engineering design isn't finding *an* answer — it's showing why *this* answer over the alternatives. A design doc that only describes what was built is a post-hoc narrative. A design doc that shows goals, rejected alternatives, and tradeoffs lets reviewers (and future agents) understand the constraints and extend the design without re-deriving it.
+
+For UI features, the same principle applies one level deeper: the hardest part isn't picking affordances, it's matching each affordance's shape to the job it serves and the cost of getting it wrong. A spec that lists goals and "the page has a list, an add button, and an edit affordance" produces designs that look complete on paper and fail in use. The per-affordance reasoning is where the design lives, and the design doc has to show it.
+
+## Design document structure
+
+| Section | Purpose | Required? |
+|---|---|---|
+| **Goals** | What are we trying to achieve? | Yes |
+| **Non-Goals** | What are we explicitly *not* solving? | Yes — constrains scope |
+| **Current State** | What already exists that the new design must compose with or replace. | Yes for refactor specs |
+| **Approach** | High-level design of the system | Yes |
+| **Interaction shapes** | Per-affordance mechanism choices, justified against jobs. Lives inside Approach. | Yes for UI features |
+| **Alternatives** | Other approaches considered and why this was chosen | Yes — this is where judgment lives |
+| **Details** | Key implementation specifics (not exhaustive) | Yes |
+| **Tradeoffs** | Pros and cons of the chosen approach | Yes |
+| **Open Questions** | Unresolved decisions blocking implementation | If applicable |
+| **Future Work** | Deferred improvements or features | If applicable |
+| **References** | External docs, specs, or code consulted | If applicable |
+
+## Guidelines
+- **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
+- **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
+
+When the spec modifies, replaces, or unifies behaviour that already exists, the Approach section is not the first place the design happens. Before you propose a new model, you owe yourself and the reader a grounded account of what is already shipped. Skipping this step produces specs that invent vocabulary in conflict with the codebase, miss shipped invariants the new design must preserve, and surface the conflicts at review time instead of at draft time.
+
+### What "refactor spec" covers
+
+This applies to any spec that touches existing behaviour, not only specs explicitly named "refactor." If your design touches a controller, a service helper, a reference doc, a type, or a piece of user-facing copy that already exists, you are refactoring. The current-state audit applies.
+
+### Required: a Current State section in the spec
+
+The Current State section sits between Non-Goals and Approach. It documents what is already shipped that the new design must reconcile with. It is not a description of the bug or the gap; it is a description of the working code as it exists today, in the codebase's own vocabulary.
+
+The section should contain:
+
+- **The native model.** What types, enums, fields, and statuses are already on the data model. If the data layer already has a status enum, the new layer must compose above it, not replace it.
+- **The shipped helpers.** Pure functions, view-model builders, copy tables, and controllers that already produce the kind of judgement the new design proposes. Quote the names, the inputs, and the values they produce.
+- **The shipped vocabulary.** The exact labels, enum literals, and copy strings the codebase uses today. If the existing code calls something "Stalled" and the new spec calls it "stuck," that conflict is a finding, not a freedom.
+- **The shipped invariants.** Priority orderings, recovery-channel distinctions, deadline rules, and any other already-encoded knowledge the new design must preserve or explicitly supersede.
+- **Other scattered attributes the unifying design touches.** The point of a unifying spec is to know what it unifies. List the call sites.
+
+### What to read before you draft
+
+For any refactor spec, at minimum:
+
+- The controller or service that owns the surface the refactor touches.
+- The pure helpers (`lib/` or equivalent) that already produce judgements in the same shape.
+- The relevant pages in `reference/` (or equivalent project documentation) — they describe what shipped and often encode invariants not visible from a single file.
+- The existing tests for the shipped behaviour. Test names often surface the vocabulary the codebase uses.
+- The fixtures and seed data, when the refactor touches anything that gets persisted in JSON columns or fixture files.
+
+If you do not know what to read, grep the codebase for the user-facing words the new design would use (`stuck`, `waiting`, `complete`, `done`, `status`, etc.) before drafting. Those greps surface every place the codebase already has a dialect.
+
+### What the Current State section is not
+
+- **Not a problem statement.** Goals and Non-Goals say why the design exists; Current State says what it composes with.
+- **Not the Approach in disguise.** Current State documents what is shipped; Approach proposes what changes. If your Current State paragraphs start proposing changes, move them to Approach.
+- **Not exhaustive code archaeology.** The audit covers what the new design touches or supersedes — not every CSS rule.
+
+### Why this matters
+
+Refactor specs without a Current State section produce two failure modes that show up at review:
+
+- **Vocabulary conflicts.** The new design names something that already has a different name in the codebase. Reviewers spend the review reconciling words instead of evaluating the design.
+- **Lost invariants.** The shipped code encodes a distinction the new design erases without noticing — a recovery-channel split, a priority ordering, a deadline rule. The spec promises unification but actually drops shipped behaviour, and the reviewer has to catch it because the spec did not document that the invariant existed.
+
+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.
+
+## 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:
+
+**Entry points → Logic → Data**
+
+| Layer | Responsibility | Examples |
+|---|---|---|
+| **Entry points** | Parse transport-specific input, delegate to logic layer, format output | HTTP controllers, CLI commands, message consumers, event handlers, view rendering |
+| **Logic** | Business rules, domain validation, orchestration | Services, use-cases, domain models, view-model builders |
+| **Data** | Persistence, external APIs, file I/O | Repositories, ORM clients, API clients, queue publishers |
+
+### Key principles
+
+- **Dependencies flow inward** — entry points depend on logic; logic depends on data. Never the reverse.
+- **Entry points are thin dispatch** — parse, call, format. No business rules, no direct data access.
+- **Logic owns the rules** — all domain validation, calculations, and orchestration live here. This layer is transport-agnostic and testable in isolation.
+- **Data access is encapsulated** — the logic layer calls data abstractions; it doesn't construct raw queries or import database clients directly.
+- **Each layer has its own design skill** — before writing code in a layer, check the `skills/` directory for the matching design skill (e.g., controller design, service design, data model design, web UI design).
+
+### Why this matters for agents
+
+Layering violations are the most common architecture mistake in generated code. The typical failure: an agent reads the data-access skill, builds correct services, then writes entry points that bypass those services and call the data layer directly. Reading the entry-point design skill (e.g., controller skill) before writing entry-point code prevents this.
+
+### Applying to different project types
+
+| Project type | Entry points | Logic | Data |
+|---|---|---|---|
+| Web API | Express routes/controllers | Service modules | Prisma, API clients |
+| CLI tool | Command handlers | Core logic modules | File I/O, config |
+| Event-driven | Message consumers | Processing services | Queue publishers, DB |
+| Web UI (server-rendered) | View templates + view rendering | Controller view-model builders + services | Service layer, API clients |
+| Library/SDK | Public API surface | Internal modules | — |
+
+## For UI features: interaction shapes
+
+When the feature has a user-facing surface — anything the user touches a screen for — the Approach section MUST include an **Interaction shapes** subsection before moving to Details. This is where the design lives. Skipping it produces specs that look structurally complete and converge on whatever pattern the existing page already uses, regardless of whether that pattern fits the jobs at hand.
+
+The pass has four steps.
+
+### 1. Enumerate the major affordances
+
+List every thing the user reaches for that the spec implies — every primary action button, every row interaction, every edit verb, every delete verb, every navigation between contexts, every creation of something new, every confirmation of a destructive action, every status indicator the user is meant to read.
+
+If you cannot enumerate the affordances, you have not yet designed; you have described a surface in general. Affordances are the unit of UI design.
+
+### 2. Name the JTB and the frequency × consequence
+
+For each affordance, name:
+
+- **The job to be done** it serves. Trace back to the jobs the requirements spec produced. If the affordance does not serve a named job, it shouldn't exist.
+- **Frequency** — how often the user reaches for this affordance. Daily? Weekly? Once per relationship?
+- **Consequence** — what happens if it fires wrongly, or what the user is committing to. Reversible? Affects others? Affects the user's reputation or money?
+
+Frequency × consequence is the design-shape signal. The two dimensions together pick the mechanism.
+
+### 3. Choose a mechanism and justify it
+
+The mechanism vocabulary:
+
+- **Direct manipulation** — tap a value, it becomes an input, tap away or Enter to save. No form, no Save button. Best for **high-frequency low-stakes** edits where the user wants to feel in control of one detail at a time.
+- **Inline expansion** — a form expands within the current surface. Best for **low-stakes structured edits where the user wants to stay in context** and the surrounding context is part of the edit decision.
+- **Sheet / drawer** — an ephemeral surface overlays the current one and dismisses on completion. Best for **low-frequency creation or focus tasks** that need attention but not navigation. Good cross-device feel; sheet on mobile, drawer on desktop.
+- **Modal** — a blocking overlay. Best for **genuinely modal decisions** — one decision must be made before anything else can happen. Easy to misuse; the bar for modal is "the user truly cannot proceed without resolving this." Most things people make modal should be sheets or pages.
+- **Dedicated page** — navigation to a new context. Best for two cases: (a) **jobs that share a subject** (a person, an account, a workflow, an order) and need the subject's full surface — history, related context, multiple affordances of its own; and (b) **jobs about navigating across subjects** (a list of subjects).
+- **Confirmation sheet** — an ephemeral surface that names the consequences of an action before the user commits. Best for **destructive or hard-to-reverse actions**, especially when the action affects related things (deleting a person who has open work).
+- **Status indicator** — a non-interactive piece of UI that reports state. Best for the **high-frequency read** that anchors every visit ("what's happening right now").
+
+Justify each mechanism choice against frequency × consequence. The justification should make the failure mode of the alternative explicit. *"Inline expansion because the edit is structured and the surrounding row context informs the edit"* is a real justification. *"Inline expansion because that's what the page already does"* is not.
+
+### 4. Check each choice against the stance
+
+The `feature-requirements` skill produces a stance — a one-paragraph statement of what the surface is and isn't, in the user's frame. After choosing mechanisms, check each one against the stance.
+
+If the stance says *"this is the agent's start-of-shift dashboard, not a workspace"* and the mechanism choices produce workspace-like density (rows with five visible affordances each), the choices violate the stance. Either the choices need revision or the stance does. Specs whose stance and affordance shapes don't match produce designs that contradict themselves.
+
+### Page / surface count is derived, not asserted
+
+The number of pages, sheets, drawers, and overlays in the final design is a **consequence of the per-affordance mechanism choices**, not an independent design decision. If editing-a-person warrants a dedicated page (because direct manipulation per field needs space and the person is a subject with related context), and adding-a-person warrants a sheet, and viewing-the-roster warrants a list, the design has **three surfaces — by derivation**.
+
+If editing warrants inline expansion and that expansion fits the existing list surface, the design has one surface — also by derivation.
+
+A spec that asserts page count up front ("we'll keep this on one page to minimize surface area") and then rationalizes the affordance choices around that assertion has the order wrong. Mechanism choices come first; surface count follows.
+
+### What the per-affordance pass produces
+
+The Interaction shapes subsection should read as a small table the rest of the spec can be checked against:
+
+| Affordance | JTB it serves | Frequency × consequence | Mechanism | Justification |
+|---|---|---|---|---|
+
+For each row, the justification names *why this mechanism fits this job's shape* and *how the choice reads against the stance*. Three to seven rows is typical for a single-feature spec.
+
+### Anti-patterns to watch for
+
+- **Inheriting the existing pattern without question.** "The current page does X with inline expansion; the new spec also uses inline expansion." If you cannot defend the mechanism against the job's frequency × consequence, the inherited pattern needs to be questioned regardless of who wrote it first.
+- **Defaulting to `confirm()` for destructive actions.** A native confirm asks for assent without surfacing consequences. For an action that affects related things (deleting a person who has open assignments), a confirmation sheet that names what's affected is the right shape; `confirm()` is the cheap shape.
+- **Defending a mechanism with "X is bad."** "Modals stack badly on mobile" argues against modal, not for inline. If the right alternative is a sheet or a dedicated page, that's what should be in the spec. Every "not X" needs a corresponding "yes Y" with its own justification.
+- **Treating all jobs as warranting the same affordance class.** Edit and delete on every row, with the same visual weight, is the CRUD-table default. It is rarely the right answer for any specific feature. Different jobs warrant different affordances.
+- **Producing a page count by minimization.** "Keep it on one page" without per-affordance reasoning is the failure mode this section is meant to prevent. If your spec's surface count comes from a frugality voice rather than from the affordance table, redo the affordance table.
+
+### 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?*

package/skills/{reqs.feature-documentation.skill.md → boop-product-design-feature-documentation/SKILL.md}

@@ -1,5 +1,10 @@
+---
+name: boop-product-design-feature-documentation
+description: "When you need to document a complex feature, function or system"
+metadata:
+  category: reqs
+---
 # Feature Documentation
-When you need to document a complex feature, function or system
 - 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.

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

@@ -0,0 +1,111 @@
+---
+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."
+metadata:
+  category: reqs
+---
+# Feature Requirements
+
+Be sure to read [reference/tenets.ref.md](../reference/tenets.ref.md) for overarching principles that apply to all features.
+
+## When you need to define what a feature should accomplish before designing how to build it
+
+Define product requirements that articulate the **jobs the user is trying to accomplish**, what success looks like for each, and where the boundaries are — before diving into technical design. Requirements should be clear enough to guide implementation decisions while leaving room for engineering judgment on how to achieve the jobs.
+
+The currency of this skill is **jobs to be done**. Every downstream artifact — pages, surfaces, affordances, schemas, endpoints — should be traceable back to a named job. If you cannot answer "which job does this serve?" for a piece of the design, either name the job or cut the piece.
+
+## When you receive a brief or vague directive
+
+**Be an advisor, not just an executor.** A major audience for boop is non-technical founders. Their directives are often incomplete — not because they're wrong, but because they haven't thought through all the implications yet. When someone gives you a 2-3 sentence business outline, resist the urge to immediately start designing or building. Instead, ask clarifying questions that help them think through what they actually need.
+
+**Push back on ambiguity, but don't interrogate.** Ask 3-5 focused questions that surface the most consequential unknowns — who the users are, what jobs they need to accomplish on this surface, what "done" means for a first version. Skip questions you can reasonably infer or defer. The goal is to fill gaps that would change your approach, not to produce a comprehensive requirements document before writing a line of code.
+
+**Frame questions as trade-offs, not open-ended prompts.** Instead of "what features do you want?" ask "would you rather launch with X and add Y later, or do you need both on day one?" Concrete options help non-technical users think through implications they wouldn't surface on their own. When you spot a likely edge case or missing piece, name it: "You mentioned user accounts — do you need roles/permissions, or is everyone equal for now?"
+
+**Know when you have enough to proceed.** Once you understand the user, the primary jobs they need to accomplish, and the first-version boundaries, move forward. You can always ask more questions as specifics emerge during design. Don't let clarification become a blocker — the point is to avoid building the wrong thing, not to achieve perfect upfront specification.
+
+## Start with jobs, not features
+
+Before user story, before goals, before approach: name the **jobs to be done**. A job is the progress a specific user is trying to make in a specific situation. Jobs are stable; the solutions vary.
+
+**List the jobs in frequency order.** For each, write what success looks like *in the user's words*. The frequency-ordered job list is the most important artifact this skill produces — every later design decision is traceable back to it.
+
+For example, the jobs on a support agent's ticket-queue page might be:
+
+1. "Tell me what needs my attention right now so I can focus on what's mine to handle" — opens the page every time
+2. "Let me respond to or reassign tickets that are waiting on me" — many times a day
+3. "Show me what's stuck or escalated so I can unblock it" — rarely, but high-stakes when it happens
+
+The frequency order surfaces design trade-offs that a feature list alone hides. Above, job #1 is dominant — the page's primary visual element should answer it. Job #3 is rare but high-stakes — it deserves a clear path even though it's not the first thing the user sees. A flat "let the agent manage their queue" treats all three the same and serves none of them well.
+
+**Name the non-jobs explicitly.** What jobs is this surface NOT supporting? On the queue page, "let me browse historical resolution trends across all queues" is a non-job — it belongs elsewhere. Naming non-jobs prevents the design from drifting into them and makes the trade-off visible to the next reader.
+
+**Frequency × consequence is the design-depth signal.** A high-frequency, high-consequence job needs depth — its own page, dedicated affordances, deliberate interaction. A low-frequency, low-consequence job tolerates terseness. Use this to decide where to invest design effort.
+
+## Take a stance
+
+A spec without an opinion is a checklist. Once jobs are named, **take and defend a stance** on what this surface is for and what it isn't, in the user's frame. A real stance reads like:
+
+> "This isn't a ticket archive. It's the agent's start-of-shift dashboard. The page should feel like walking up to your desk and seeing what's on fire, not querying a database."
+
+The stance is a one-paragraph summary that downstream decisions can be checked against. If a decision conflicts with the stance, either the decision is wrong or the stance needs updating.
+
+A generic stance ("provide a usable interface for managing tickets") is no stance at all. Force it concrete; force it in the user's voice; force it to draw a contrast with what it isn't. The "isn't" half is where the work happens — a stance that names what something replaces or refuses is doing more work than one that only names what it does.
+
+## Then write the user story
+
+Once jobs are named and a stance is taken, the user story flows from them. A user story is a **concrete scenario** — a specific user, doing one of the jobs, in a real situation, with real time pressure or real stakes.
+
+**A bad user story** describes the company's intent: "During a customer demo, we want to show how the product can analyze user data." That's a demo story, not a user story — it centers the company, not the user.
+
+**A good user story** centers the user's situation and motivation: "Maya opens the queue on her phone between calls. She has two minutes before the next one. She wants to know if any ticket needs her response before she picks up again."
+
+Good stories make trade-offs obvious. The phone-between-calls detail forces a mobile consideration. The two-minute window forces a brevity consideration. "Needs her response" forces a primary-action consideration. None of these come out of a generic story.
+
+## Frame goals and non-goals explicitly
+
+Goals are the outcomes the user achieves on this feature — they derive from the named jobs but read as observable outcomes ("Maya can see what needs her attention within ten seconds of opening the page") rather than capability statements ("implement attention surfacing"). Non-goals are equally important: they prevent scope creep and document intentional trade-offs.
+
+For instance, if a feature aims to "let the agent act on pending tickets inline" but explicitly does *not* aim to "let the agent batch-resolve across every queue," that constraint guides architectural choices and manages stakeholder expectations. When non-goals address common assumptions or adjacent problems, they prevent expensive detours during implementation.
+
+Every goal should trace to at least one job. Every non-goal should trace to at least one non-job. If you cannot trace one, either the job analysis is incomplete or the goal/non-goal is wrong.
+
+## On surface area: minimize where it doesn't help, invest where it does
+
+Prefer solutions that solve the immediate problem with minimal new surface area **where that surface isn't earning its keep** — fewer tables, fewer endpoints, fewer configuration options. Features should extend naturally as needs evolve, not require rewrites.
+
+**But:** design depth where the user's primary job needs focus. The rule is "minimize what doesn't help the dominant job; invest where it does." The failure mode to watch for is *treating all jobs as equally weighted* and minimizing across the board — that produces flat surfaces that serve no job well, even though every section of the spec is technically present.
+
+Two practical tests:
+
+- For every piece of proposed surface (a page, an affordance, an endpoint, a column, a flag), name the job it serves. If you can't, cut it.
+- For every named high-frequency or high-stakes job, name what surface is dedicated to it. If you can't, you're probably under-designing where it matters.
+
+This isn't about building for imaginary futures — it's about matching investment to the jobs the user actually does on this surface. The substrate (data model, schemas, services) stays minimal and flexible; the surface gets depth where the dominant jobs warrant it.
+
+## When determining how to measure success
+
+**Define success metrics per job.** Each job named in the JTB list should have an observable measure of whether the user accomplished it. Metrics should be checkable, not subjective:
+
+- A timer ("under 30 seconds from page open to first action")
+- A click count ("zero clicks to see current status")
+- A behavior ("a reply template added on the templates page is immediately selectable in the composer without a reload")
+- A degradation gate ("on a queue of 100 tickets the page still loads under 200ms p95")
+- A data-integrity check ("the same assignee never appears as two separate chips due to capitalization differences")
+
+For multi-stage rollouts, specify adoption milestones per job: "by v1.0 the dominant job is supported on a mobile-first layout; the maintenance jobs follow in v1.x." Metrics ground the conversation — they prevent "done" from becoming subjective and help prioritize quality investments.
+
+## Order of operations (recap)
+
+When writing a feature spec, work the following order. Each step depends on the prior step being honest.
+
+1. **Jobs to be done**, in frequency order, with success in the user's words
+2. **Non-jobs** — what this surface explicitly isn't for
+3. **Stance** — what this is and isn't, in the user's frame, in one paragraph
+4. **User story** — concrete scenario where a primary job plays out
+5. **Goals** — observable outcomes traced to jobs
+6. **Non-goals** — scope guards traced to non-jobs
+7. **Surface-area discipline** — minimize where the user gets nothing, invest where the dominant jobs need focus
+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.

package/skills/{docs.reference-integration.skill.md → boop-product-design-reference-integration/SKILL.md}

@@ -1,5 +1,10 @@
+---
+name: boop-product-design-reference-integration
+description: "When you need to integrate new knowledge into the project's `reference/` directory after completing a feature, fixing a bug that changes behavior, or adding a capability."
+metadata:
+  category: docs
+---
 # Reference Integration
-When you need to integrate new knowledge into the project's `reference/` directory after completing a feature, fixing a bug that changes behavior, or adding a capability.
 
 ## Goal
 Keep `reference/` as a living wiki of **what the system actually is right now** — not a pile of per-feature pages. New knowledge is blended into existing concept pages; new pages are created only when a genuinely new concept has no home.

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

@@ -0,0 +1,136 @@
+---
+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."
+metadata:
+  category: writing
+---
+
+# Technical Prose
+
+## Goal
+
+**Write so a fresh reader, agent or human, can pick up the artifact cold.** The reader will not have been in the planning session. They will not have grown up with the project's internal vocabulary. They have to read the prose and act.
+
+When that constraint is met, the writing is doing its job. When it is not — when the reader has to translate from agent-shorthand into normal language before they can start — the writing is taking the reader's time and burning attention they should be spending on the work.
+
+## When to use this skill
+
+- Writing or reviewing the body of a bd issue, especially a follow-up issue created during a feature run.
+- Composing a chat response that explains a finding, a recommendation, or a piece of context.
+- Updating reference documentation or any artifact a future agent will read.
+- Reviewing prose another agent produced. The same anti-patterns affect every agent's output.
+
+## 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.
+- **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.
+
+## The translation test
+
+Before you send a sentence or save an artifact, **read it aloud as if explaining it to a colleague who has not been in the planning session**. If the colleague would stop and ask "what do you mean by X?" or "what does Q-C refer to?" or "where does this term come from?" — rewrite that part of the prose. The colleague's stop-and-ask is the signal you have compressed past what the reader can decode.
+
+The colleague does not have to be a non-technical person. The test is whether a technical reader who lacks the specific context can follow.
+
+## Anti-patterns
+
+### 1. Cryptic identifiers without anchor
+
+Phrases like "Q-C resolved (option a)" or "per A3/D2/G-7" reference internal labels (questions in a plan, design choices) without setting up what those labels mean. Even a reader who can guess loses time.
+
+**Fix.** Reference the label and explain what it covers in the same sentence. "Question C of the plan, which asked whether to keep the existing bucket vocabulary, was resolved as: keep the buckets." Or rephrase to remove the label entirely if the meaning travels without it.
+
+### 2. Abstract noun stacks
+
+Phrases like "3-signal operator-routing collapse" or "DashboardBucket taxonomy" or "multi-state arithmetic implementation" compress a paragraph of meaning into a noun-stack that takes the reader real work to unpack.
+
+**Fix.** Use verbs. "The bucket categorizes each property by combining three signals about what the operator should do next." "The DashboardBucket logic that groups properties by operator-action shape."
+
+### 3. Pseudo-code in prose
+
+Lines like `needs-decision = pending outbox draft` or `blocked = computeStuckCount > 0` ask the reader to parse expressions in the middle of sentences. The reader's eye has to switch modes.
+
+**Fix.** Describe the rule in words. "A property is **Blocked** when it has at least one stuck task — that is, when `computeStuckCount` returns more than zero." Keep the code reference in a parenthetical or a follow-up sentence, not as the main grammatical structure.
+
+### 4. Code identifiers used as everyday nouns without explanation
+
+Sentences like "inherits the unified model TRANSITIVELY through computeStuckCount" use code identifiers as if they were plain English nouns the reader already knows.
+
+**Fix.** Wrap the identifier in a phrase that tells the reader what it is. "The bucket logic calls `computeStuckCount`, which Slice 2 already migrated to the unified model. Because the call is indirect, the bucket gets the unified model for free."
+
+### 5. Coined compound adjectives
+
+Phrases like "patch-and-forget" or "ship-then-document" or "see-and-decide" compress an idea into a hyphenated label. They feel sharp but make the reader unpack the label every time they meet it.
+
+**Fix.** Use the verb phrase. "Quietly papered over." "Ship first, document after." "Look before deciding."
+
+### 6. Internal tooling nouns without translation
+
+Writing "file the decision as real beads" assumes the reader maps "beads" to your issue tracker. Outside the project the word means jewelry.
+
+**Fix.** Say the everyday word. "File the decision as a real issue." Use the tool name only when the choice of tool matters to the point.
+
+### 7. Naming a file inline as a noun
+
+Sentences like "the shape the feedback_current_is_not_correct memory should produce" insert a file slug into a sentence as if it were a noun. The slug reads like a stack trace.
+
+**Fix.** Use the everyday name for the principle and let a link or footnote carry the file reference. "The principle we just saved" or "the rule about not auto-preserving current behaviour."
+
+### 8. Telegraphic ALL-CAPS for emphasis
+
+When you find yourself writing "NOT" or "UNCONDITIONALLY" or "TRANSITIVELY" in all caps to make the point land, the underlying sentence is not pulling its weight.
+
+**Fix.** Restructure the sentence so the emphasized word is where the reader's eye naturally lands. "The leaf pass returns `awaiting-operator-reply` for every in-progress customer task, regardless of whether the operator has replied" — the sentence shape makes "regardless" the punchline without needing caps.
+
+### 9. Em-dashed clause chains
+
+Sentences with three or more em-dashes read as breathless. Restructure into separate sentences, or use parentheses for genuine asides.
+
+### 10. Engineering jargon as everyday metaphor
+
+Words like "load-bearing," "first-class," "atomic," "fail open," "downstream/upstream" have specific meanings in their technical contexts. Used loosely as substitutes for "important" or "default" or "before/after," they read as performative jargon. Use the plain word that fits the sentence.
+
+### 11. Designer-shorthand verbs
+
+Saying "three directions named" or "surfaced this" or "captured as" treats writing-down as a metaphorical act when "three options" or "showed this" or "wrote" is the plain word. The shorthand reads as compression rather than craft.
+
+### 12. Chopped fragments and dropped subjects
+
+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."
+
+## bd issue bodies specifically
+
+bd issue bodies have a higher bar than chat responses because:
+
+- The reader claims the issue and starts working from the body alone. There is no preceding conversation for them to fill in.
+- The same body may be read by multiple agents on different days. Each fresh agent rebuilds the context from the prose.
+- Issue bodies tend to inherit each other's style: when one agent writes a cryptic body, the next agent's body inherits the same patterns. The cure has to be applied early.
+
+**Every bd issue body should answer four questions:**
+
+1. **What is the situation?** Set up the context the reader needs. Do not assume they were in the planning session.
+2. **What is the work?** State concretely what needs to happen — files to change, behaviours to add, tests to verify.
+3. **What is the verification?** Name how the reader will know the work is done — a test, a behaviour check, a sign-off.
+4. **Where are the breadcrumbs?** Always include explicit file paths, function names, plan references, and test file paths. A "Breadcrumbs" section at the end of the body is a reliable shape.
+
+When the body involves a question that needs an operator decision rather than agent judgement (a parity boundary, a product choice, a copy choice), say so explicitly. Tell the agent claiming the issue not to auto-resolve and to surface the question via the available "ask the operator" mechanism, or to hand the issue back.
+
+## Worked example
+
+A real follow-up issue body, written in the agent-shorthand style:
+
+> Q-C resolved (option a, wf-3blv.7.8): keep the DashboardBucket taxonomy on the All-properties list — do NOT adopt the five-value pill (wrong axis; would break parity). The bucket is a 3-signal operator-routing collapse: needs-decision = pending outbox draft (workers, NOT node-progress), blocked = computeStuckCount>0 (stuck), ready = operator next-action exists (yours), in-motion = else.
+
+The same content, rewritten in technical prose:
+
+> The All-properties list groups each property into one of four buckets that describe what the operator should *do* next: **Needs decision**, **Blocked**, **Ready**, and **In motion**. We considered replacing those four buckets with the new five-value progress pill (`Not started` / `In motion` / `Waiting` / `Stalled` / `Closed`) during the parent feature's Slice 4. The answer was no — the four buckets describe operator-action shape, while the five-value pill describes how the work is progressing. They are different axes, and switching to the pill would change what the operator sees on the list.
+>
+> Three of the four bucket signals come from sources we are not touching in this refactor (pending draft messages from the workers data, and the operator's next-action list). The fourth signal — `computeStuckCount` — reads from the workflow tree, and was migrated to the unified model in Slice 2. Because the bucket logic calls `computeStuckCount` indirectly rather than reading the tree itself, it inherits the unified model for free.
+
+The first version compresses meaning into 60 words of jargon. The second uses about 130 words and is readable cold by anyone. The cost of the second is a few seconds for the writer. The benefit is that every future reader of the issue spends less time decoding and more time on the work.
+
+## Related
+
+- `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.

package/skills/design.engineering-design.skill.md

@@ -1,60 +0,0 @@
-# Engineering Design
-When you need to design a feature or system and communicate the technical decisions.
-
-## Goal
-**Make the decision visible, not just the solution.**
-
-The hardest part of engineering design isn't finding *an* answer — it's showing why *this* answer over the alternatives. A design doc that only describes what was built is a post-hoc narrative. A design doc that shows goals, rejected alternatives, and tradeoffs lets reviewers (and future agents) understand the constraints and extend the design without re-deriving it.
-
-## Design document structure
-
-| Section | Purpose | Required? |
-|---|---|---|
-| **Goals** | What are we trying to achieve? | Yes |
-| **Non-Goals** | What are we explicitly *not* solving? | Yes — constrains scope |
-| **Approach** | High-level design of the system | Yes |
-| **Alternatives** | Other approaches considered and why this was chosen | Yes — this is where judgment lives |
-| **Details** | Key implementation specifics (not exhaustive) | Yes |
-| **Tradeoffs** | Pros and cons of the chosen approach | Yes |
-| **Open Questions** | Unresolved decisions blocking implementation | If applicable |
-| **Future Work** | Deferred improvements or features | If applicable |
-| **References** | External docs, specs, or code consulted | If applicable |
-
-## Guidelines
-- **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
-- **Design docs live in `specs/`** — see [engineering-planning](./proj.engineering-planning.skill.md) for how designs become work plans
-
-## 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:
-
-**Entry points → Logic → Data**
-
-| Layer | Responsibility | Examples |
-|---|---|---|
-| **Entry points** | Parse transport-specific input, delegate to logic layer, format output | HTTP controllers, CLI commands, message consumers, event handlers |
-| **Logic** | Business rules, domain validation, orchestration | Services, use-cases, domain models |
-| **Data** | Persistence, external APIs, file I/O | Repositories, ORM clients, API clients, queue publishers |
-
-### Key principles
-
-- **Dependencies flow inward** — entry points depend on logic; logic depends on data. Never the reverse.
-- **Entry points are thin dispatch** — parse, call, format. No business rules, no direct data access.
-- **Logic owns the rules** — all domain validation, calculations, and orchestration live here. This layer is transport-agnostic and testable in isolation.
-- **Data access is encapsulated** — the logic layer calls data abstractions; it doesn't construct raw queries or import database clients directly.
-- **Each layer has its own design skill** — before writing code in a layer, check `skills/index.md` for the matching design skill (e.g., controller design, service design, data model design).
-
-### Why this matters for agents
-
-Layering violations are the most common architecture mistake in generated code. The typical failure: an agent reads the data-access skill, builds correct services, then writes entry points that bypass those services and call the data layer directly. Reading the entry-point design skill (e.g., controller skill) before writing entry-point code prevents this.
-
-### Applying to different project types
-
-| Project type | Entry points | Logic | Data |
-|---|---|---|---|
-| Web API | Express routes/controllers | Service modules | Prisma, API clients |
-| CLI tool | Command handlers | Core logic modules | File I/O, config |
-| Event-driven | Message consumers | Processing services | Queue publishers, DB |
-| Library/SDK | Public API surface | Internal modules | — |

package/skills/reqs.feature-requirements.skill.md

@@ -1,33 +0,0 @@
-# Feature Requirements
-
-Be sure to read the [reference/tenets.ref.md](../reference/tenets.ref.md) for overarching principles that apply to all features. 
-
-## When you need to define what a feature should accomplish before designing how to build it
-
-Define product requirements that articulate the problem to be solved, who benefits, and what success looks like—before diving into technical design. Requirements should be clear enough to guide implementation decisions while leaving room for engineering judgment on how to achieve the goals.
-
-## When you receive a brief or vague directive
-
-**Be an advisor, not just an executor.** A major audience for boop is non-technical founders. Their directives are often incomplete — not because they're wrong, but because they haven't thought through all the implications yet. When someone gives you a 2-3 sentence business outline, resist the urge to immediately start designing or building. Instead, ask clarifying questions that help them think through what they actually need.
-
-**Push back on ambiguity, but don't interrogate.** Ask 3-5 focused questions that surface the most consequential unknowns — who the users are, what the core workflow looks like, what "done" means for a first version. Skip questions you can reasonably infer or defer. The goal is to fill gaps that would change your approach, not to produce a comprehensive requirements document before writing a line of code.
-
-**Frame questions as trade-offs, not open-ended prompts.** Instead of "what features do you want?" ask "would you rather launch with X and add Y later, or do you need both on day one?" Concrete options help non-technical users think through implications they wouldn't surface on their own. When you spot a likely edge case or missing piece, name it: "You mentioned user accounts — do you need roles/permissions, or is everyone equal for now?"
-
-**Know when you have enough to proceed.** Once you understand the core user, the primary workflow, and the first-version boundaries, move forward. You can always ask more questions as specifics emerge during design. Don't let clarification become a blocker — the point is to avoid building the wrong thing, not to achieve perfect upfront specification.
-
-## When writing requirements for a new feature
-
-**Start with the user story.** Every feature should articulate a concrete scenario: who is trying to accomplish what, and why it matters. For example, "During a customer demo, we want to show how GPT-4 can analyze publisher data so that sales prospects see advanced capabilities in action." Good stories make trade-offs obvious—they reveal which users to prioritize, which problems are urgent, and which nice-to-haves can wait. Stories create shared context between product, engineering, and stakeholders.
-
-## When defining feature scope
-
-**Frame goals and non-goals explicitly.** Goals define what the feature must accomplish—the specific outcomes or capabilities that constitute success. Non-goals are equally important: they establish boundaries, prevent scope creep, and document intentional trade-offs. For instance, if a feature aims to "provide confidence-of-being-human signals via VAT/ACT" but explicitly does *not* aim to "replace MRC IVT systems," that constraint guides architectural choices and manages stakeholder expectations. When non-goals address common assumptions or adjacent problems, they prevent expensive detours during implementation.
-
-## When choosing between implementation approaches
-
-**Minimize complexity and preserve forward compatibility.** Prefer solutions that solve the immediate problem with minimal new surface area—fewer tables, fewer endpoints, fewer configuration options. Features should extend naturally as needs evolve, not require rewrites. For example, storing permissions in JSON blobs instead of creating multiple relational tables may simplify v1 while keeping the door open for future normalization if query patterns demand it. Always ask: what's the simplest approach that doesn't foreclose future options? This isn't about building for imaginary futures—it's about avoiding premature commitments that make future change expensive.
-
-## When determining how to measure success
-
-**Define success metrics and adoption paths.** Requirements should articulate how you'll know the feature works in practice: which user flows must succeed, which edge cases must degrade gracefully, and what operational characteristics matter (latency, throughput, error rates). For multi-stage rollouts, specify adoption milestones: "SSPs pass-through first, native verification later" clarifies what's needed for launch versus what's a future enhancement. Metrics ground the conversation—they prevent "done" from becoming subjective and help prioritize quality investments.