@boopkit/cap-product-design 0.6.9 → 0.6.10

package/package.json

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

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

@@ -57,6 +57,8 @@ The stance is a one-paragraph summary that downstream decisions can be checked a
 
 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.
 
+**The word means only this, and it does not travel.** A stance is the positioning paragraph described above. It is not a synonym for an assumption, an unproven decision, or a working hypothesis — those have ordinary words, and using "stance" for them produces prose a reader cannot decode, because the reader has to guess which of two unrelated meanings is in play. Outside a spec's own stance paragraph, write the ordinary word.
+
 ## 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.
@@ -115,6 +117,13 @@ When writing a feature spec, work the following order. Each step depends on the
 
 Steps 1–3 are where this skill earns its keep. Skipping them produces well-structured feature checklists with no design clarity downstream.
 
+## Appendix — house writing examples
+Here are examples using a natural human writing style which should be emulated in most writing - documents, conversations, requirements, analysis, etc.
+### Example writing
+John connected with Northgate Property Partners (NPP) via a past school connection Dana Kessler, a co-founder of NPP. They are very interested in automating much of the low-judgement activities of their staff and real estate agents. Their first priority is listing prep - exactly our strengths.
+Dana forwarded an extensive RFP to build this platform, based mostly on material she learned at a convention in Denver. This RFP provides a very clear view on what a high end (top 1% by dollar volume) brokerage feels would be extremely valuable.
+While this sounds exciting it is unclear whether this RFP is a 'work for hire' (they own the IP) or whether a true partnership with Wishfleet as platform and product provider is possible.
+
 ## Related
 
 - [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — specs live in `specs/`; break their lines semantically so edits diff cleanly.

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

@@ -105,6 +105,46 @@ When a reader points at one fault, treat it as an example rather than an invento
 - 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?
 
+## Appendix — house writing examples
+Here are examples using a natural human writing style which should be emulated in most writing - documents, conversations, requirements, analysis, etc.
+
+### Example writing 1
+John connected with Northgate Property Partners (NPP) via a past school connection Dana Kessler, a co-founder of NPP. They are very interested in automating much of the low-judgement activities of their staff and real estate agents. Their first priority is listing prep - exactly our strengths.
+Dana forwarded an extensive RFP to build this platform, based mostly on material she learned at a convention in Denver. This RFP provides a very clear view on what a high end (top 1% by dollar volume) brokerage feels would be extremely valuable.
+While this sounds exciting it is unclear whether this RFP is a 'work for hire' (they own the IP) or whether a true partnership with Wishfleet as platform and product provider is possible.
+
+### Example writing 2
+The CompanyName franchise network has been using the ApplicantStack system to manage their hiring process, for both CareGuides and Team Leads. In order to provide an easy to consume set of insights and recommendations the data from ApplicantStack is being ingested, standardized and made available internally via Looker and externally via weekly Insights reports delivered through email.
+
+As the insights and recommendations were being developed it became apparent that the ApplicantStack system had been customized by many franchises over time such that every franchise appears differently than any other franchise - there was no way to easily evaluate performance to identify opportunities or to compare a franchise with peer groups.
+
+To address this issue a new ‘unified hiring model’ was developed which is able to describe all franchises’ hiring workflows and unlock the ability to provide insights and recommendations.
+
+This document will explain the unified hiring model and how ApplicantStack data and workflows are mapped.
+
+*Principles and perspectives on workflow insights*
+*Structure the workflow into 'process', 'activity' and 'status'*
+Across all franchises there are 150 distinct 'applicant stack stages'. However these really describe only five processes and a number of activities within a process. The processes are Apply, Screen, Interview, Offer and Hire. Candidates are in only one process, independent of what the current activity may be (eg. schedule interview, conduct interview, review interview notes, etc). A candidate has only one of three possible statuses - open, paused, closed. It is important to track which process a candidate is in when they are closed out (ie. no longer being considered). ApplicantStack does not do this due to franchises being required to use 'stage' to indicate status (ie. Do Not Pursue). Separating a candidate's process from a candidate's status allows for determining *which* process candidates are dropping out from, and so allows calculating performance rates for each process.
+
+### Example writing 3
+A startup evolves through several stages, each with its own set of goals and tactics. What works in one stage may not work in another - it's important to know what stage you are in and use appropriate best practices.
+
+*Discovery stage*
+The goal at this stage is to discover what people want and are willing to pay.
+The primary skills at this stage are scrappiness and communication.
+
+*Product fit*
+The goal at this stage is to take ‘what works’ and make it repeatable and solid. Continue working on Product Market Fit (PMF) until you can feel customers pulling you along rather than you pushing them into the product.
+
+### Example writing 4
+*Principles*
+The way people work together determines success or failure in any endeavor.
+For organizations building and operating technology based products and services the first key to unlocking success is the mindset of the people. People spend most of their time in either a development mindset or an operations mindset.
+- Development (Dev): the growth mindset engine of learning, experimentation, and evolution.
+- Operations (Ops): the execution engine, focused on consistent delivery, results, and accountability.
+
+Customers don’t care how you’re organized—they only care about what you deliver. Avoid Conway’s Law pitfalls: align teams to customer journeys, not internal functions. Structure follows mission, not the other way around.
+
 ## 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.

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

@@ -17,6 +17,58 @@ metadata:
 
 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.
 
+**Two properties do most of the work.** The anti-patterns below are all failures of one or the other, so aim at these directly rather than checking thirteen rules. Both are properties of what you *deliver*; see [Drafting and delivering are different acts](#drafting-and-delivering-are-different-acts) for why that distinction carries most of the weight.
+
+**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, not opposite ones: `table`, `column`, `foreign key`, `function`, `parameter`, `import`, `public function`, `index` are all 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, an abbreviation, or a shorthand defined earlier in the document 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 explaining**. Those are the passages a reader is most likely to read alone, out of order, or long after the work.
+
+## Drafting and delivering are different acts
+
+**The draft is where you work out what is true. The delivery is for the reader.** Emitting a draft is fine and often necessary — thinking in prose is how a position gets found, and a rule that says "write it plainly the first time" asks you to have finished thinking before you start. Nothing here constrains the draft. Write the argument, the derivation, the false starts, whatever gets you to the position.
+
+**What must be done well is delivering the final writing — whether a draft is used or not.** A draft might be how you arrived at the position, it may carry vividness that does not serve the eventual reader, it may open where you started rather than where they need to begin, and so on. None of that is a defect in the draft. It is simply shaped for the writer, and delivery is where it gets shaped for the reader.
+
+So delivery is its own act, whether or not anything preceded it:
+
+1. **Draft, if it helps.** Work out what is true, in whatever shape that takes.
+2. **Deliver against purpose.** Name who reads this and what they must be able to do once they have read it. Then read what you have back as that reader and condense or remove whatever does not serve that job — however nice it sounds.
+
+### Revise against purpose, not against how it reads
+
+"Does this read well" cannot be the standard, because your own taste is the instrument that fails. Prose that argues a case, names an idea memorably, or reaches for a vivid image is exactly what good writing feels like from the inside. That feeling is strongest at the moment the writing has drifted from informing the reader into persuading them, so the signal you would use to decide whether to revise is inverted by the thing you are trying to catch.
+
+Naming the reader's job replaces that judgement with one you can actually make. The question is not "is this good" but "after reading this, can they do the thing?"
+
+**The reader's needs are contextual, not a fixed property of the artifact.** What a piece of writing must do depends on who is reading it and what they need *at the time* — the same specification serves someone deciding whether to build differently from someone building it, and a closeout note read the next morning differently from the same note read six months later. So there is no table of rules per artifact type to look up. Work out the reader and their situation each time; the examples below show the shape of that reasoning rather than a set of answers to reuse.
+
+- A **goal in an issue**: an agent who must build the right thing. They need to know what capability to deliver. Three sentences of argument for the requirement, with the requirement last, makes them extract it.
+- A **spec**: a reader deciding and then building. They need the position and its constraints, not the search that found it.
+- A **handoff or closeout**: someone picking the work up cold. They need state, not story.
+- A **chat reply to the operator**: someone deciding what to do next. They need the finding and the choice, not the route you took to it.
+
+Nobody in that list needs convincing. They have already committed to the work; the writing exists to let them do it. When you catch yourself building a case, check who you imagine you are persuading — usually the answer is that you are still persuading yourself, which means it is not ready to deliver.
+
+### Name how the writing should sound, not only the reader
+
+"Write it well" is not a standard you can check, which is why knowing that your taste fails does not by itself stop it failing. Naming the kind of writing you are aiming at — how formal it sounds, how much it argues, who it sounds like it was written by — is checkable, because you can ask whether a specific sentence belongs to it.
+
+The default for anything a colleague will act on — a spec, an issue, a design note, a handoff — is **technical English of the kind a product manager writes in a requirements document.** Direct statements. Ordinary technical vocabulary. No sentence whose job is to make another sentence land.
+
+Three questions decide it, and each is answerable about a single sentence:
+
+- Does this sentence carry a fact, a requirement, or a decision? If it carries only emphasis, rhythm, or a build-up to the next sentence, delete it.
+- Would a product manager write this in a requirements document? Not "would a good writer be pleased with it."
+- Is every word here either ordinary English or a term the industry defined? A word that is neither — vague but technical-sounding, or coined on the spot — is reaching for the feeling of precision.
+
+### How this differs from the translation test
+
+The translation test below asks whether the reader can **parse** the text. This asks whether they can **act** on it. Prose passes the first and fails the second routinely: every sentence is ordinary English, the meaning is available, and the reader still has to do work you should have done — extract the requirement from the argument, decode a coined framework, convert a stated principle into the cases they are about to write.
+
+Run both. They catch different failures, and the parse test passing is not evidence about the act test.
+
 ## When to use this skill
 
 - Writing or reviewing the body of a bd issue, especially a follow-up issue created during a feature run.
@@ -108,6 +160,24 @@ Reaching for an invented label — "the spine" for a workflow's ordered steps, "
 
 **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.
 
+### 14. A title or heading that states a thesis instead of naming the subject
+
+A heading in the form "X, not Y" argues a side of a contrast the reader was never on the other side of. It reads as a position to be defended, so the reader arrives at the section braced rather than informed. The same construction inside a sentence is usually rhetoric carrying no content: "delete the copies first, not last" says nothing that "delete the copies first" does not.
+
+The tell is that the heading could be agreed or disagreed with. A heading names what a section is about, and that is not a claim at all.
+
+**Fix.** Name the subject. "Environment-based configuration," not "Configuration belongs in the environment, not in the repository." "The lookup exists in four forms," not "Four duplicates, not one function to convert." Keep a contrast only where both sides carry information the reader needs: distinguishing two real mechanisms is content, taking a side is not.
+
+### 15. A common word the product domain has already spent
+
+Every domain claims some ordinary words. Using one as jargon for something else makes the reader disambiguate on every occurrence, and they will sometimes get it wrong without noticing they did.
+
+Before adopting a common word as a term, check whether the product's own vocabulary already uses it. In real estate every property has a street *address*, so a document that means a URL has to say URL. In publishing a *page* is the thing being sold. In logistics a *route* is a vehicle's itinerary. In finance a *position* is a holding. The collision is invisible to the writer, who has one meaning in mind, and expensive for the reader, who has two.
+
+This is the mirror of anti-pattern 13. That one is about inventing a private word for something already named; this one is about reusing a named word for something else.
+
+**Fix.** Use the precise industry term for what you mean — URL, endpoint, column, parameter, request — and leave the common word to the domain that owns it. Where both meanings genuinely appear in one document, say which one every time rather than relying on context to carry it.
+
 ## bd issue bodies specifically
 
 bd issue bodies have a higher bar than chat responses because:
@@ -125,6 +195,22 @@ bd issue bodies have a higher bar than chat responses because:
 
 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.
 
+## Specs specifically
+
+A spec is read by someone deciding whether to build it and by someone building it, often months apart, and neither was in the conversation that produced it.
+
+**Open with a line naming the reader and what they must be able to do, not a line describing the document's subject.** "What we need to build, and in what order" describes the document. "For the engineer decomposing this into tasks: what changes, in what order, and which decisions are already settled" names a reader and a job.
+
+The difference is not presentational. That opening line is the only place where the delivery question — who reads this, and what must they be able to do afterwards — leaves a visible trace in the artifact. A spec whose first line describes itself is usually a spec where nobody asked. Once the line exists, everything below it has a standard to be judged against, and so does every later edit.
+
+## Reviewing prose, including your own
+
+**A review of the phrasing may not report content findings.** The two substitute for each other, and content always wins, because a factual error can be checked against something outside the text while a fault in the phrasing can only be judged against the prose you are looking at. A reviewer who sets out to check the writing, finds four real factual errors, and stops has done a content review and will believe the writing was reviewed.
+
+So name which pass you are running, and run them separately. In the phrasing pass, a factual error you happen to notice gets written down and set aside, not reported as the outcome.
+
+**When a correction arrives, re-run the whole standard rather than sweeping the class that was named.** A reader who points at one fault is giving an example, not an inventory. Fixing every instance of the named pattern and stopping leaves every other pattern in place, and the fix reads as thorough precisely because the named class is now clean.
+
 ## Worked example
 
 A real follow-up issue body, written in the agent-shorthand style:
@@ -139,6 +225,46 @@ The same content, rewritten in technical prose:
 
 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.
 
+## Appendix — house writing examples
+Here are examples using a natural human writing style which should be emulated in most writing - documents, conversations, requirements, analysis, etc.
+
+### Example writing 1
+John connected with Northgate Property Partners (NPP) via a past school connection Dana Kessler, a co-founder of NPP. They are very interested in automating much of the low-judgement activities of their staff and real estate agents. Their first priority is listing prep - exactly our strengths.
+Dana forwarded an extensive RFP to build this platform, based mostly on material she learned at a convention in Denver. This RFP provides a very clear view on what a high end (top 1% by dollar volume) brokerage feels would be extremely valuable.
+While this sounds exciting it is unclear whether this RFP is a 'work for hire' (they own the IP) or whether a true partnership with Wishfleet as platform and product provider is possible.
+
+### Example writing 2
+The CompanyName franchise network has been using the ApplicantStack system to manage their hiring process, for both CareGuides and Team Leads. In order to provide an easy to consume set of insights and recommendations the data from ApplicantStack is being ingested, standardized and made available internally via Looker and externally via weekly Insights reports delivered through email.
+
+As the insights and recommendations were being developed it became apparent that the ApplicantStack system had been customized by many franchises over time such that every franchise appears differently than any other franchise - there was no way to easily evaluate performance to identify opportunities or to compare a franchise with peer groups.
+
+To address this issue a new ‘unified hiring model’ was developed which is able to describe all franchises’ hiring workflows and unlock the ability to provide insights and recommendations.
+
+This document will explain the unified hiring model and how ApplicantStack data and workflows are mapped.
+
+*Principles and perspectives on workflow insights*
+*Structure the workflow into 'process', 'activity' and 'status'*
+Across all franchises there are 150 distinct 'applicant stack stages'. However these really describe only five processes and a number of activities within a process. The processes are Apply, Screen, Interview, Offer and Hire. Candidates are in only one process, independent of what the current activity may be (eg. schedule interview, conduct interview, review interview notes, etc). A candidate has only one of three possible statuses - open, paused, closed. It is important to track which process a candidate is in when they are closed out (ie. no longer being considered). ApplicantStack does not do this due to franchises being required to use 'stage' to indicate status (ie. Do Not Pursue). Separating a candidate's process from a candidate's status allows for determining *which* process candidates are dropping out from, and so allows calculating performance rates for each process.
+
+### Example writing 3
+A startup evolves through several stages, each with its own set of goals and tactics. What works in one stage may not work in another - it's important to know what stage you are in and use appropriate best practices.
+
+*Discovery stage*
+The goal at this stage is to discover what people want and are willing to pay.
+The primary skills at this stage are scrappiness and communication.
+
+*Product fit*
+The goal at this stage is to take ‘what works’ and make it repeatable and solid. Continue working on Product Market Fit (PMF) until you can feel customers pulling you along rather than you pushing them into the product.
+
+### Example writing 4
+*Principles*
+The way people work together determines success or failure in any endeavor.
+For organizations building and operating technology based products and services the first key to unlocking success is the mindset of the people. People spend most of their time in either a development mindset or an operations mindset.
+- Development (Dev): the growth mindset engine of learning, experimentation, and evolution.
+- Operations (Ops): the execution engine, focused on consistent delivery, results, and accountability.
+
+Customers don’t care how you’re organized—they only care about what you deliver. Avoid Conway’s Law pitfalls: align teams to customer journeys, not internal functions. Structure follows mission, not the other way around.
+
 ## Related
 
 - `boop-project-mgmt-beads-planning` — its "self-contained briefing" rule for issue bodies leans on the patterns described here.