@boopkit/cap-product-design 0.6.11 → 0.6.13

package/capability.json

@@ -10,6 +10,9 @@
     "boop-product-design-feature-documentation",
     "boop-product-design-feature-requirements",
     "boop-product-design-reference-integration",
+    "boop-product-design-knowledge-backfill",
+    "boop-product-design-docs-sweep-workflow",
+    "boop-product-design-reference-restructure-workflow",
     "boop-product-design-thought-partnership",
     "boop-writing-technical-prose",
     "boop-writing-documents",

package/package.json

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

package/skills/boop-product-design-docs-sweep-workflow/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: boop-product-design-docs-sweep-workflow
+description: "When `specs/` has piled up with documents nobody has looked at in months and you need to know which are finished, which have gone stale, and which are the only surviving record of real work, follow this process: measure the set rather than read it, classify each document against what the issue tracker says (the close reason, not the status), pass the gate before archiving anything, and make the mechanical fixes while surfacing the judgement calls. The document-set sibling of issue-sweep. Not for folding one shipped feature into `reference/`."
+metadata:
+  category: docs
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# Docs Sweep
+
+When you need to sweep `specs/` (and the `reference/` pages its documents point at) for documents that have fallen out of step with what shipped, follow this.
+It has the shape of issue-sweep over a different population, and the same promise: the operator's judgement is spent only where it has to be.
+
+## Goal
+
+**A closed issue is not evidence that a document is finished.**
+
+The obvious sweep archives every spec whose issues are all closed, and it is often wrong.
+Issues get closed without their work: triaged away in a cleanup pass, culled on the rule that a real problem will come back, or superseded by a design that never shipped.
+Archiving the spec that cites them buries the only account of that work, and a reader who trusts the tracker concludes it was done.
+
+So the default disposition is **correct it and leave it where it is**, not archive it.
+A document at the top of `specs/` is usually there on purpose.
+You are looking for documents whose *claims* have gone stale, and only incidentally for the ones that are finished.
+
+The second mistake is treating the sweep as reading.
+A large `specs/` is too much to read, and reading is not what finds the drift.
+Measure first, and read only what the measurement flags.
+
+**This sweep asks whether a document says true things.**
+Whether the work it describes is still worth doing is a product question for the operator, and out of scope here.
+Say so when you hand off.
+
+## 1. Measure, do not inventory
+
+Derive the population with a few lines of script each time; never hand-build a list, and never write one into a document, because a snapshot starts rotting the day it is written.
+`bd list --all --limit 0 --json` gives every issue with its `status` and `close_reason`, and the filesystem gives the rest:
+
+- **Every issue id each document cites**, and what became of it: open, closed with a delivery, or closed without the work.
+- **Documents no open issue points at.** Not a defect, but the population least likely to have been maintained, so look there first.
+- **Relative links that do not resolve.** Archiving moves a file and leaves the documents pointing at it where they were, so this is usually the largest source of rot.
+- **Names shared between `specs/` and `specs/history/`.** Sometimes deliberate, a remainder spec beside its archived original, and sometimes two copies of one document that differ only in annotations.
+
+If the project has a check that compares closed features with archived specs, read what it reports as candidates, not as work.
+Such a check cannot tell a living document from a forgotten one, and you never archive a living document to turn a check green.
+
+## 2. Classify against what the tracker says
+
+Read the close *reason*, never the status.
+`closed` covers work delivered and work thrown back, and the difference decides the disposition.
+
+| What you find | What it means | Disposition |
+|---|---|---|
+| Header says complete, nothing open | finished | **archive**, after the gate in stage 3 |
+| Cited issues closed, reasons describe a delivery | shipped | **archive**, after checking `reference/` carries it |
+| Cited issues closed without the work | dropped, never built | **correct it**: the document is now the record and must say so |
+| No issues cited, deferred work described in prose | never filed | **keep**, and name it on the roadmap |
+| Header says parked, or names an external trigger | not near-term | **move** to the project's parked location, if it has one |
+| A plan or findings document whose spec is archived | orphaned | **archive** beside the spec it decomposed |
+| Two copies, one annotated with what shipped | superseded draft | **delete** the un-annotated one |
+| A `.ref.md` page under `specs/` | current state in the future-state directory | **move to `reference/`** and repoint every inbound link |
+
+A document can be more than one of these.
+Work the corrections first; they are what the sweep is for.
+
+## 3. The gate before archiving
+
+Archiving is the one move here that can lose something.
+Before moving any document to `specs/history/`, answer:
+
+> **What does this document say that is written down nowhere else?**
+
+If anything (a deferred item nobody filed, an observation left for the next reader, a decision recorded only in prose), the document is not archivable yet.
+Either that content lands somewhere reachable first, or the document stays.
+Do not file an issue just to clear the gate: a paper-cut is often better kept in the prose that explains it than in a queue entry nobody reads.
+Say what you found and let the operator decide.
+
+Two kinds of document fail the gate on their own terms:
+
+- **A remainder spec stays while anything in it is pending**, even when every item has an issue.
+  A file in `specs/` signals an unfinished thread far more loudly than one issue among hundreds.
+- **`specs/history/` holds documents about work that shipped.**
+  A superseded document whose work was never built is deleted, once you have confirmed its content is carried forward or worth nothing, because its place in history asserts that it describes something real.
+
+And two checks before the move:
+
+- **The reference integration happened.** The document usually names the pages it was folded into; confirm the sections exist rather than trusting the sentence.
+- **Nothing links to it at the old path**, and its own relative links resolve from the new one. A file moving a directory deeper needs every `../` in it re-counted.
+
+## 4. Act on the mechanical, surface the judgement
+
+Corrections, link repairs, moves between directories and deletions of superseded duplicates are reversible, and yours to make.
+Commit them grouped by concern rather than one commit per file; a reviewer reads the concern, not the file list.
+
+Three things are the operator's, and settling them yourself is the failure mode:
+
+- **Whether a spec still describes something worth building.** Out of scope, by the boundary above.
+- **Whether a document that is the sole record of unbuilt work should become an issue.** Filing is usually the lazier move; report what you found.
+- **A document marked as a mirror of another repository**, or otherwise "do not edit here." Its broken links are an artifact of mirroring, and fixing them locally makes the next re-sync worse.
+
+## 5. Close the loop
+
+- Re-run the stage-1 measurements; the links resolve and no document cites a closed issue as tracked work.
+- Every population you found but did not clear is named on the project's roadmap or plan, with a trigger, so its absence is a decision rather than an oversight.
+  Name the population and its shape; do not enumerate it.
+- The handoff says which half of the work ran: "the tracking half of the sweep has run; the staleness half has not" keeps the next agent from assuming both.
+
+## Related
+
+- [`boop-product-design-knowledge-backfill`](../boop-product-design-knowledge-backfill/SKILL.md) — when the sweep finds specs that shipped and were never folded into `reference/`; that is one of this sweep's outcomes, and that skill does the folding.
+- [`boop-product-design-reference-integration`](../boop-product-design-reference-integration/SKILL.md) — for the stage-3 check that a document's reference integration actually happened, and for doing it when it did not.
+- `boop-project-mgmt-stray-disposition` — before you close an issue during the sweep; its rule that closing an issue orphans the documents citing it is how future culls avoid creating the drift this sweep has to find.
+- `boop-project-mgmt-issue-sweep-workflow` — when a correction starts turning into a code change; its eligibility rules say whether it still fits a sweep.

package/skills/boop-product-design-knowledge-backfill/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: boop-product-design-knowledge-backfill
+description: "When you need to integrate new knowledge from a set of specs or completed work that was not documented in reference at the time it shipped. This often happens when a feature is developed under a tight deadline and the team prioritizes shipping over documentation, or when work was done before the reference system was fully established."
+metadata:
+  category: docs
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# Knowledge Backfill
+
+   **a. Integrate into reference:**
+   - Follow the `boop-product-design-reference-integration` skill for the subjects the shipped work created or changed; its rule decides where each one lands, including when one earns a page of its own.
+     This is NOT "create a new page for the feature".
+   - Expect buried subjects here more than anywhere else.
+     Several specs may each have added to the same subject without any of them giving it a page, so its whole footprint is often seen for the first time during backfill.
+     When the burial you find reaches well past the subjects these specs touched, record it and run the reference-restructure workflow afterwards rather than restructuring inside the backfill.
+   - Update cross-links between affected reference pages.
+   - Remove or update any reference content that is now outdated.
+  
+   **b. Archive the spec:**
+   - Move the completed spec from `specs/` to `specs/history/` (create the directory if it doesn't exist).
+   - If any aspects of the spec were NOT implemented (deferred, descoped, or punted), extract those into a new revised spec in `specs/` that captures just the remaining work. Reference the archived spec for full context.
+   - The archived spec should be the full original — do not edit or trim it.
+
+## Related
+
+- [`boop-product-design-reference-integration`](../boop-product-design-reference-integration/SKILL.md) — for step a of every spec you process; this workflow decides what to backfill and in what order, and that skill decides where each piece lands on the page.
+- [`boop-product-design-reference-restructure-workflow`](../boop-product-design-reference-restructure-workflow/SKILL.md) — when the backfill shows subjects buried across `reference/` beyond the ones these specs touched.
+- [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md) — when extracting the unimplemented remainder into a revised spec; that spec is read cold by someone with none of the backfill's context.
+- [`boop-product-design-docs-sweep-workflow`](../boop-product-design-docs-sweep-workflow/SKILL.md) — before archiving, when you cannot yet tell which specs in the set shipped and which only had their issues closed; that sweep sorts them.

package/skills/boop-product-design-reference-integration/SKILL.md

@@ -12,23 +12,57 @@ metadata:
 # Reference Integration
 
 ## 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.
+
+**`reference/` describes what the system actually is right now, and its set of pages is the index of the subjects the system has.**
+A reader arrives with a question about one subject, such as "how do we store files?" or "how do email attachments work?", and should find one page whose title names that subject and answers it.
+Knowledge that is correct but sits inside a page about something else fails that reader as surely as knowledge that was never written down.
+
+Integration keeps that index true as the system grows, and the index breaks in two directions:
+
+- **Sprawl:** one page per feature, a graveyard of disconnected documents that nobody reads.
+- **Burial:** a subject dissolved into pages about other subjects, so that no title leads to it.
+
+Weigh the two equally.
+Blending new knowledge into the page where its subject lives guards against sprawl; giving a subject its own page once it has outgrown its host guards against burial.
+Neither move is the safe default, and neither needs a special defence.
+
+Burial is the one that creeps up unseen, because subjects grow by accretion.
+Each change adds a little to a subject, correctly placed beside the context it depends on, so no single integration ever looks like the moment a new subject arrived, and some section of some large page can always hold one more paragraph.
+That is why the process below has two passes: place the knowledge, then re-read the shape.
 
 ## Principles
 
 - **Reference is the current truth.** Specs describe the intended future; reference describes what shipped. After a feature lands, reference must reflect reality.
-- **Entity/concept pages, not feature pages.** Don't create `matching-feature.ref.md` — instead update `matching-system.ref.md`, `database.ref.md`, and any other concept pages the feature touches.
+- **A page is about a subject, not a feature.**
+  Don't create `matching-feature.ref.md`; update `matching-system.ref.md`, `database.ref.md`, and whichever other subjects the feature touched.
+  Tell a subject from a feature by asking whether future work would extend the page.
+  A subject that later changes will add to earns a page; a page that only one feature would ever touch is a feature page.
+- **Subjects are named from the reader's side.** The word a reader would look up is the subject's name, and a feature's own name is rarely that word: nobody looks up a checkout redesign to learn how a receipt is stored.
 - **Wiki-style cross-links.** Every reference page should link to related pages using relative markdown links (e.g., `[service layer](service-layer.ref.md)`). When adding content, add links in both directions — the page you're editing and the pages you're referencing.
 - **Blend, don't append.** New content should be woven into the existing narrative at the right location, not dumped at the bottom under a "New: feature X" heading. The reader shouldn't be able to tell which paragraph was added when.
 
 ## Process
 
-### 1. Identify affected concepts
-Read the spec/feature summary and list every concept the feature touches. Examples: a new API endpoint affects the REST API ref, the service layer ref, and possibly the database ref. A new background job affects the job system ref and whatever domain it operates in.
+### 1. Name the subjects the change touches
+
+Read the spec, the feature summary or the change itself, and list each piece of new knowledge.
+For each one, ask what question would bring someone looking for it, and what word they would use for its subject.
+That word names the subject, whether or not a page for it exists yet.
+For example, a new API endpoint usually touches the REST API, the service layer and possibly the database; a new background job touches the job system and whatever subject the job works on.
+
+**A list of pages handed to you is a starting point, not the scope.**
+A plan or a task often names the pages to update ("at least these three").
+That list was written before the work existed, so it can only name pages that existed then, and it cannot name a subject the work created.
+Update the pages it names, then name the subjects from what actually shipped, and give each the treatment below.
 
-### 2. For each concept, check for an existing page
-- **Page exists** → Read it, understand its structure, then merge new content into the appropriate sections. Update any tables, lists, or diagrams. Add cross-links to other affected pages.
-- **No page exists** → Create a new `{concept}.ref.md` page. Follow the structure patterns of existing reference pages in the project. Add cross-links from related existing pages to the new page.
+### 2. Find each subject's home
+
+**A subject has a home only when a page's title names it.**
+A paragraph inside a page about another subject is a tenant, not a home.
+
+- **A page names the subject** → read it, understand its structure, then merge the new content into the right sections. Update any tables, lists or diagrams, and add cross-links to the other pages you touch.
+- **The subject lives only as a tenant inside another page** → placing the new knowledge there first is fine, because it keeps the text beside the context it depends on. It does not yet answer the reader's question; step 4 decides whether the subject now needs its own page.
+- **No page mentions the subject** → if future work would extend it, create `{subject}.ref.md`, following the structure of the project's existing pages, and link to it from the related pages. If nothing would ever extend it, it is a detail of a subject that has a home; place it there.
 
 ### 3. Merge guidelines
 - Match the voice and style of the existing page — don't introduce a different tone.
@@ -37,17 +71,73 @@ Read the spec/feature summary and list every concept the feature touches. Exampl
 - If the feature introduces new terminology, define it where it first appears and link to it from other pages.
 - Remove or update any content that is now outdated or contradicted by the new feature.
 
-### 4. Cross-linking checklist
+### 4. Re-read each subject's whole footprint
+
+After placing the knowledge, read everything `reference/` now says about each subject, not just your diff.
+Search for the subject's name and its synonyms across every page.
+
+When the subject has grown into several paragraphs, is spread across pages, or has become a page-sized section inside a page about something else, **promote it**: give it its own page, and leave a short summary and a link in each page that used to hold it.
+Promotion is an ordinary result of integration, not a failure to blend.
+
+**Promote when you find it, in the same change.**
+That includes a buried subject the current work only touched in passing.
+Cleaning up as you go is how the index stays true; a note for a later sweep is how it drifts.
+The one exception is an explicit instruction to keep the change minimal, such as an urgent fix that has to move fast.
+Then file an issue for the promotion, naming the subject and the pages that hold it, so the burial is recorded rather than forgotten.
+This step reaches only the subjects a change touches; when the footprint read shows burial across much of `reference/`, beyond what one change should carry, that backlog is the reference-restructure workflow's job.
+
+For example, a project's file storage conventions grew over several changes as bullets under one external service in its architecture page: which service to call, then a key prefix per environment, then the access policy, the cleanup command and the tests.
+The handling of files attached to inbound email grew as a paragraph and six bullets inside a section about the email channel, on a page about a different workflow.
+Every fact had been placed correctly, and neither subject had a page a reader could find.
+The closeout that buried them had been handed three existing pages to update, and treated that list as the whole job.
+Run again with the reader's-side naming and the footprint read, the same closeout gave both subjects pages of their own.
+
+### 5. Cross-linking checklist
 After editing, verify:
 - [ ] Every page you modified links to every other page you modified (where the relationship is meaningful)
-- [ ] New concepts are linked from the most relevant existing overview/index sections
+- [ ] New and promoted subjects are linked from the most relevant existing overview or index sections
+- [ ] Every page a subject was promoted out of keeps a short summary and a link to the subject's new page
 - [ ] No orphan pages — every new page is reachable from at least one existing page
 
-### 5. Naming conventions
-- File: `{concept}.ref.md` (e.g., `matching-system.ref.md`, `user-auth.ref.md`)
+### 6. Naming conventions
+- File: `{subject}.ref.md` (e.g., `matching-system.ref.md`, `user-auth.ref.md`), named with the word a reader would look up
 - Use kebab-case, singular or plural based on what reads naturally
 - Suffix is always `.ref.md`
 
+## A capability catalog, if the project keeps one
+
+Some projects keep one page that tells a non-engineer what the product can do today: for somebody writing website copy, briefing a salesperson, or answering a prospect.
+Many projects have no such page, and nothing here asks for one; skip this section if yours does not.
+
+A catalog is written at the level of the job the customer is doing rather than by screen or route, and it carries a section naming what the product deliberately does not do.
+The rest of this skill governs it, plus one rule that applies to no other page: **most changes must not touch it.**
+A catalog that absorbs every change stops describing the product and becomes a second changelog, and then nobody trusts it enough to quote from it, which was the only reason to have it.
+
+Update the catalog only when a change alters what a customer could truthfully be told, which means a yes to at least one of these:
+
+1. Somebody can now do something they could not do before, or rely on something they could not rely on: a capability arrived, a capability was withdrawn, or who the product serves changed.
+2. A sentence already in the catalog is now false, including one discovered never to have been true.
+   A bug fix that merely makes shipped behavior match what the catalog already claims is not an update.
+3. A gap named in the section on what is not built was filled or widened.
+
+If all three are no, the knowledge belongs in the subject pages.
+
+Then check that the change can be described to somebody who has never seen the interface.
+"A customer can export a month of orders to a spreadsheet" is a capability, and so is "a reply sent from the customer's usual mail program lands back on the right conversation."
+If the only way to describe the change is to name a page, route, component, column or field, it is how a capability is implemented rather than a capability, and it goes in the subject pages.
+
+Changes that do merit an update: a request can now go to several recipients at once, with their replies matched back to it; a plan can now change after it has started; text messaging ships, which deletes a line from what is not built.
+Changes that do not: a button changed color, moved or got a clearer label; one screen was split into two, or two merged, with the same capability on them; a query got faster, or a defect was fixed so that behavior matches what the catalog already says; a new staff-only or admin screen, unless a customer would notice it; a new form field that captures something the catalog already covers.
+
+The section on what is not built rots fastest, and it is the half a salesperson leans on to avoid over-promising.
+A change that builds something listed there removes or narrows that line in the same commit; shipping the capability and leaving the disclaimer standing is worse than never having written it.
+
+Three things not to do with the catalog:
+
+- **Do not add it to a must-touch integration checklist.** A check that asserts the catalog was edited every time turns the test above into a formality; most changes should record "no change a customer could be told about" and move on.
+- **Do not publish it.** Turning the catalog into a slide, a shared document or a web page is separate work that somebody asks for explicitly.
+- **Do not let it become a changelog.** No dated entries and no "New in August" heading; a reader should not be able to tell which release added which sentence.
+
 ## When boop has changed a page this project rewrote
 
 Some pages in `reference/` arrived with a boop capability.
@@ -79,6 +169,8 @@ A `SKILL.md` the project has edited is not blended: its edits move into the `PRO
 
 ## Anti-patterns
 - **One page per feature** — creates a graveyard of disconnected documents nobody reads
+- **Burying a subject** — leaving a subject that has outgrown its host as a section of a page about something else, so no title leads a reader to it; it breaks the index as surely as sprawl does
+- **Treating a page list as the scope** — updating only the pages a plan or task named, when the work created a subject none of them is about
 - **"See also" link dumps** — links should be inline where the concept is discussed, not in a footer list
 - **Copy-pasting from the spec** — specs use future tense and rationale; reference uses present tense and describes what is, not why it was chosen
 - **Leaving stale content** — if the feature changes existing behavior, update or remove the old description
@@ -87,4 +179,5 @@ A `SKILL.md` the project has edited is not blended: its edits move into the `PRO
 
 - [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — `reference/` pages are edited far more often than they are written; semantic line breaks are what keep those edits reviewable.
 - [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md) — when blending new content into an existing page; the merged paragraph has to read as though it was always there, and matching a page's voice starts with writing full sentences.
-- `boop-knowledge-backfill` — when the gap is not one feature's knowledge but a backlog of shipped work that was never written down; that workflow decides what to process and in what order, then sends each spec back here.
+- [`boop-product-design-knowledge-backfill`](../boop-product-design-knowledge-backfill/SKILL.md) — when the gap is not one feature's knowledge but a backlog of shipped work that was never written down; that workflow decides what to process and in what order, then sends each spec back here.
+- [`boop-product-design-reference-restructure-workflow`](../boop-product-design-reference-restructure-workflow/SKILL.md) — when step 4 finds buried subjects across the set rather than in the subjects this change touched; it measures the whole of `reference/` and promotes each subject in its own commit.

package/skills/boop-product-design-reference-restructure-workflow/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: boop-product-design-reference-restructure-workflow
+description: "When `reference/` has grown by accretion and subjects a reader would look up have no page of their own (they live as sections inside pages about something else, or in pieces across several pages), follow this process: measure the whole set rather than read it, write down the candidate subjects, then promote each one in a worktree, one commit per subject, for the operator to review as a diff. The whole-set counterpart of reference-integration, which promotes a buried subject one change at a time."
+metadata:
+  category: docs
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# Reference Restructure
+
+When you need to reorganise `reference/` so that each subject a reader would look up has a page titled for it, follow this.
+It is not a check of whether the pages are still true, and not a backfill of missing knowledge.
+The knowledge is already written down, correctly; the problem is that nobody can find it.
+
+## Goal
+
+**A reader who comes to `reference/` with a question about a subject finds one page whose title names that subject and answers it.**
+The set of page titles is the index of the subjects the system has.
+
+Reference integration keeps that index true one change at a time: after placing new knowledge, it reads everything now said about the subject and promotes the subject when it has outgrown its host.
+That only reaches subjects a change touches.
+Subjects that accreted before anyone checked, or that no recent change has touched, stay buried.
+This workflow applies the same rule to the whole set at once, so it uses the same tests: a page is about a subject, not a feature, and a subject is named with the word a reader would look up.
+
+## 1. Work in a worktree
+
+Every change this makes is a move of existing prose, and the operator reviews it as a diff.
+Run it on its own branch in its own worktree, never in the primary checkout and never on main.
+
+## 2. Measure, then read only what the measurement flags
+
+A large `reference/` is too much to read, and reading is not what finds a buried subject anyway.
+Measure instead:
+
+- **Section size against page subject.** List every page's `##` and `###` sections with their line counts.
+  Flag a section when it is large (as a rough guide, more than 40 lines, or a heading with sub-headings of its own) **and** its heading names a different subject from the page's title.
+  A long section about the page's own subject is not a finding.
+- **Scatter.** For the terms that name subjects, the words a reader would search for, count the pages that discuss each one beyond a passing mention.
+  A subject explained in pieces across four pages, with no page of its own, is a finding even if no single piece is large.
+- **Title check.** For each flagged subject, confirm no page is already titled for it.
+  If one is, the knowledge moves to that page rather than to a new one.
+
+Then read the flagged sections, and only those, well enough to write the candidate list.
+
+## 3. Write the candidate list down before anything moves
+
+Which subjects get pages, and what each page is called, are decisions about the index itself, so the operator should see them together and not only as a diff.
+Commit the list in the worktree as `specs/reference-restructure-findings.md`, one entry per candidate:
+
+- **The subject**, named as a reader would name it, and the question it answers.
+- **Where it lives now:** each page and section, with line counts.
+- **The proposed page:** its file name and title.
+- **What moves and what stays:** each host page keeps a short summary and a link.
+- **Whether future work would extend it.** A subject later changes will add to earns a page; one that only a single feature will ever touch stays where it is.
+
+Also list briefly what you considered and rejected, and why, so the operator can overrule you.
+
+Then carry on to step 4 unless the operator asked to approve the list first.
+Because each subject is its own commit, dropping one is a single revert, and the list is what lets the operator read the run as a set of decisions rather than one large diff.
+
+## 4. Promote each subject, one commit per subject
+
+For each subject on the list:
+
+- Create the page, following the structure of the project's existing reference pages.
+  Move the text, and do not rewrite it beyond what the new context needs; a move that also edits content is hard to review.
+- Leave a short summary and an inline link in each host page, where the text used to be.
+- Keep old anchors resolving: when a heading moves, keep it in the host with its summary, or add an `<a id>` for the old fragment.
+- Repoint every link that pointed at the moved text, across `reference/`, `specs/`, `skills/` and comments in the code, and add the new page to the overview or index sections that should list it.
+- Commit, naming the subject and the pages it came from.
+
+For a long list, file one issue per subject under an epic and run them as a loop in the worktree, so that each commit maps to one decision.
+
+## 5. Hand off
+
+Report the commits, one line per subject, and any link or anchor you could not preserve.
+The operator reviews the diff and merges; do not merge it yourself.
+
+## Anti-patterns
+
+- **Promoting by size alone.** A long page about one subject is fine; the finding is a section about a *different* subject from its page.
+- **Rewriting while moving.** Moves and edits in one commit hide the edits.
+  If a moved section is wrong, fix it in a separate commit or record it for later.
+- **Naming a page for a feature.** The new page is named for the subject a reader looks up, not for the feature that first wrote about it.
+- **Skipping the list.** Promotions without it turn a set of naming decisions into a large diff with no account of what was chosen and what was passed over.
+
+## Related
+
+- [`boop-product-design-reference-integration`](../boop-product-design-reference-integration/SKILL.md) — for the rules this applies to the whole set: what makes a subject, how to name it, and when it has outgrown its host.
+- `boop-loop-conductor` — when the candidate list is long enough to run as one issue per subject, launched in the worktree with `--no-branch`.

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

@@ -1,6 +1,6 @@
 ---
 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."
+description: "When the user wants to think out loud through a design — a feature, a capability, a strategic direction — or to drive a set of features forward with you interactively, through design, code, review and adjustment, be a thought partner, not an implementer: hold the conversation at user-and-value altitude, honor uncertainty with hypotheses rather than pretend-decisions, record each ruling where the next reader will find it, and keep software-shaped concerns downstream of the user's lived problems."
 metadata:
   category: design
 ---
@@ -15,17 +15,22 @@ metadata:
 
 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.
 
+The partnership does not end when code starts.
+When the user drives a set of features forward with you, the work cycles through design, code, review and adjustment,
+and each review brings the conversation back to design altitude: what the user saw, what it taught them, and what changes because of it.
+
 ## 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.
+- The user is driving a set of features forward with you interactively: designing one, watching it get built, reviewing it, and adjusting the design before the next.
 
 ## 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.
+- The discussion has already converged on a specific implementation approach and the user wants help executing it, with no review coming back to the design.
 
 ## Core principles
 
@@ -43,13 +48,36 @@ The right move: pick the simplest informed hypothesis, mark it explicitly as a h
 
 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.
 
+"Not enough data yet" is a ruling in its own right.
+When the user declines to choose because nothing they know yet points either way, record that as the ruling, with what would settle it, rather than leaving the question looking forgotten.
+
 ### 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
+### 4. Rulings live in the spec, not in the chat
+
+When the user rules on something — a stance, a scope cut, a hypothesis to try — write the ruling into the spec it governs, dated, and in sentences that stand on their own.
+A ruling left bare in the chat is lost to every later reader, including the agent that builds from the spec next week,
+and a ruling that only makes sense beside the conversation that produced it is not much better.
+
+The spec holds judgment: the rulings, the hypotheses, and the reasons for them.
+The issue tracker holds decided work.
+Do not file an issue for something the user has not decided, and do not leave a decision only in an issue body where the next design conversation will not look for it.
+
+### 5. While iterating, the user's eye is the check
+
+When the user is reviewing changes as they land — adjusting a layout, rewording copy, trying a variation — they verify each quick edit by looking at it.
+Do not run the full suite between those edits; run it once the set of edits is done.
+
+A test that goes red on a change the user asked for is evidence about the test, not about the code.
+Ask whether the test was worth having.
+When it only pinned markup or wording the product never promised, delete it rather than updating it to pin the new markup;
+the `boop-test-audit-workflow` skill covers tests like that.
+
+### 6. 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.
 
@@ -62,6 +90,8 @@ When the user opens a design conversation:
 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.
+6. **Write each ruling down as it is made.** Put it in the spec, dated and self-contained, before the conversation moves on.
+7. **After each review, return to design altitude.** When the user has looked at what was built, start from what they saw and what it taught them, and adjust the design before the next piece is built.
 
 ## Anti-patterns
 
@@ -69,6 +99,7 @@ When the user opens a design conversation:
 - **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."
+- **Leaving a ruling in the chat.** "As we agreed above" in a spec, or a decision that exists only in the conversation, gives the next reader nothing to act on.
 - **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