janderscience-skills 0.0.0-stage → 1.0.0

package/sources/headcount/plugins/product/skills/interface-craft/references/sources.md

@@ -0,0 +1,67 @@
+# Sources — `product:interface-craft`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## Age Appropriate Design Code
+
+UK Information Commissioner's Office · UK · free to use with attribution — credit the publisher
+
+<https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/childrens-information/childrens-code-guidance-and-resources/>
+
+**Authoritative for:** What default settings, nudges and profiling are permissible in a service likely to be used by children. A statutory code, so it settles whether onboarding may default a toggle on.
+
+## CCPA regulations, California Code of Regulations title 11
+
+California Privacy Protection Agency · US-CA · public domain — quote freely
+
+<https://cppa.ca.gov/regulations/consumer_privacy_act.html>
+
+**Authoritative for:** Symmetry in choice, as law. It settles whether a consent flow where accepting is one click and declining is three is permissible — converting what is usually argued as design taste into a compliance question.
+
+## California Automatic Renewal Law, Business and Professions Code 17600-17606
+
+California Legislative Counsel · US-CA · public domain — quote freely
+
+<https://leginfo.legislature.ca.gov/faces/codes_displayText.xhtml?division=7.&chapter=1.&part=3.&lawCode=BPC&article=9.>
+
+**Authoritative for:** The concrete cancellation obligations a subscription business actually has to meet, because California's requirements are stricter than the federal floor and apply to any California customer — which in practice makes them the binding ones.
+
+## Human Interface Guidelines
+
+Apple · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://developer.apple.com/design/human-interface-guidelines>
+
+**Authoritative for:** What correct platform behavior is on Apple platforms — control semantics, navigation structure, touch targets. Its authority is not taste: deviation is grounds for review rejection.
+
+## Unicode Common Locale Data Repository
+
+Unicode Consortium · global · free to use with attribution — credit the publisher
+
+<https://cldr.unicode.org/>
+
+**Authoritative for:** Correct date, number, currency, name-order, plural and sort behavior for a locale. Settles how something should render in a given language with data rather than guesswork, and every platform's internationalization library derives from it.
+
+## WAI-ARIA and the ARIA Authoring Practices Guide
+
+World Wide Web Consortium · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://www.w3.org/WAI/ARIA/apg/>
+
+Machine-readable: <https://www.w3.org/TR/wai-aria-1.2/>
+
+**Authoritative for:** Which roles, states and keyboard interactions a given widget must implement. Settles whether Escape should close a dialog and whether a role is the right one, without appeal to preference.
+
+## Web Content Accessibility Guidelines 2.2
+
+World Wide Web Consortium · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://www.w3.org/TR/WCAG22/>
+
+**Authoritative for:** Whether a page, email or video is accessible. It is the criteria list that US Section 508, the EU's EN 301 549 and most enterprise procurement point at, so it settles any argument that reaches a buyer's accessibility requirement.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/product/skills/interface-redesign/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: interface-redesign
+description: Upgrades an existing interface to a higher standard without rebuilding it — auditing what is there, identifying what reads as generic or unfinished, and sequencing changes by impact. Use this when a product works but looks dated or default, when a redesign is being considered, when deciding whether to restyle or rebuild, or when a screen needs to look substantially better with limited effort.
+---
+
+# Interface redesign
+
+Most interfaces do not need rebuilding. They need a dozen specific things fixed, in the right order.
+
+## Audit first
+
+Go through the real product, on a real device, doing a real task. Record what you find in these
+categories — the order is the priority order:
+
+1. **Structural** — unclear primary action, competing focal points, navigation that does not match
+   the mental model. These are the only ones worth a rebuild.
+2. **Systemic** — inconsistent spacing, more type sizes than a scale would allow, palette drift,
+   components that exist in variants. High impact, mechanical to fix.
+3. **Craft** — weak hierarchy, poor contrast, unfinished states, cramped density.
+4. **Cosmetic** — dated shadows, default border radii, stock illustration.
+
+## The generic-AI-product tells
+
+These are the specific things that make a product read as unconsidered. They are worth naming
+because they are all cheap to fix:
+
+- Default framework styling left in place — the untouched button, the starter-template card.
+- One accent color used for every emphasis, so nothing is emphasized.
+- Uniform spacing everywhere, so nothing groups.
+- Centered everything, including body copy.
+- Emoji standing in for iconography.
+- Gradients on surfaces that carry no meaning.
+- Empty and error states that were never designed.
+
+## Sequencing
+
+Fix in this order, because each makes the next easier to see:
+
+1. Tokens — spacing scale, type scale, palette. This alone resolves most systemic findings.
+2. Hierarchy on the two or three highest-traffic screens.
+3. States: empty, loading, error, overflow.
+4. Component consolidation.
+5. Cosmetic pass.
+
+## Restyle or rebuild
+
+Rebuild only when the structure is wrong — when the information architecture does not match how
+people work. Everything else is a restyle, and a restyle that ships beats a rebuild that stalls.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Never
+
+- Restyle a screen whose problem is structural. New paint on a broken flow buys nothing.
+- Change navigation and visual language in the same release. When something breaks you will not know which one did it.
+- Remove a path because it looks unused without checking who uses it and what they do next.
+- Ship a redesign with no way back. Keep the old path reachable until the new one is proven.
+
+## Return contract
+
+Findings by category with severity, the sequenced plan, what you would do first if only one day were
+available, and what you deliberately are not touching.

package/sources/headcount/plugins/product/skills/interface-redesign/references/sources.md

@@ -0,0 +1,43 @@
+# Sources — `product:interface-redesign`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## CCPA regulations, California Code of Regulations title 11
+
+California Privacy Protection Agency · US-CA · public domain — quote freely
+
+<https://cppa.ca.gov/regulations/consumer_privacy_act.html>
+
+**Authoritative for:** Symmetry in choice, as law. It settles whether a consent flow where accepting is one click and declining is three is permissible — converting what is usually argued as design taste into a compliance question.
+
+## Human Interface Guidelines
+
+Apple · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://developer.apple.com/design/human-interface-guidelines>
+
+**Authoritative for:** What correct platform behavior is on Apple platforms — control semantics, navigation structure, touch targets. Its authority is not taste: deviation is grounds for review rejection.
+
+## WAI-ARIA and the ARIA Authoring Practices Guide
+
+World Wide Web Consortium · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://www.w3.org/WAI/ARIA/apg/>
+
+Machine-readable: <https://www.w3.org/TR/wai-aria-1.2/>
+
+**Authoritative for:** Which roles, states and keyboard interactions a given widget must implement. Settles whether Escape should close a dialog and whether a role is the right one, without appeal to preference.
+
+## Web Content Accessibility Guidelines 2.2
+
+World Wide Web Consortium · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://www.w3.org/TR/WCAG22/>
+
+**Authoritative for:** Whether a page, email or video is accessible. It is the criteria list that US Section 508, the EU's EN 301 549 and most enterprise procurement point at, so it settles any argument that reaches a buyer's accessibility requirement.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/product/skills/presentation-design/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: presentation-design
+description: Designs slide decks and one-pagers that carry an argument rather than decorate one — deck structure, headlines that state the takeaway, charts that make a single point, and the different rules board decks and conference talks follow. Use this to build or fix a pitch deck, board deck, or conference talk, to design a one-pager, or when a deck is dense, unfocused, or being read aloud from the slides. For social graphics, carousels and infographics, use `marketing:visual-content` instead.
+---
+
+# Presentation design
+
+## Decks
+
+**The deck is not the talk.** Slides that contain the argument make the speaker redundant and the
+reader confused. Decide which artifact you are making — a spoken-support deck or a read-alone
+document — because they have opposite rules and the hybrid fails at both.
+
+**One idea per slide.** If a slide needs a sub-argument, it is two slides. The cost of an extra
+slide is zero; the cost of a crowded one is that nothing on it lands.
+
+**Structure carries more than styling:**
+
+1. Open with the change in the world that makes this matter now.
+2. State the problem in the audience's terms, not yours.
+3. The argument, in the smallest number of steps that hold.
+4. The evidence — one chart per claim, not a dashboard.
+5. The ask, stated explicitly. A deck that ends without an ask was a briefing.
+
+**On slides:** headline states the takeaway, not the topic — "Churn concentrates in month two,"
+not "Churn analysis." If the reader only reads headlines, they should get the argument.
+
+**Charts:** one message each, labeled directly rather than through a legend, with the axis honest.
+Strip everything that is not carrying information.
+
+## Board decks and conference talks follow different rules
+
+The structure above is shaped for persuasion to a room you are in. Two of the artifacts this skill
+is asked for are not that.
+
+**A board deck is read before the meeting, not presented at it.** It goes out days ahead and is
+expected to be read, so it has to stand alone — which makes it the read-alone document, not the
+spoken-support deck.
+
+- **Separate what is for decision from what is for information**, and say which is which on the
+  page. A board meeting spent walking through updates is a board meeting with no decisions in it.
+- **Keep the format identical period over period.** The value of a board pack is comparison across
+  time, and a redesign destroys it. Same sections, same order, same metrics with the same
+  definitions.
+- **Lead with what is not working.** A pack that buries the problem on page nineteen costs
+  credibility permanently once someone finds it, and they do.
+- **Bring the open question, not only the resolved one.** A board shown finished thinking cannot
+  help and eventually stops trying.
+
+For how the meeting itself should be run and what belongs at which cadence, see
+`operations:operating-cadence`; for what has to be formally recorded, `legal-risk:corporate-governance`.
+
+**A conference talk is a performance with visual support**, and it fails in the opposite direction
+from a board pack.
+
+- **Fewer words than feels safe.** Slides are read faster than you speak, so text competes with you
+  and wins. Images, one phrase, a single number.
+- **Design for the back of a large room** and for the bottom third being invisible behind heads.
+- **The talk has to survive the projector** — assume poor contrast and bad color reproduction, and
+  never rely on a subtle tonal difference to carry meaning.
+- **Nothing on a slide should require the handout to be understood.** If the deck will be shared
+  afterward, that is a second artifact, not the same one.
+
+## One-pagers
+
+A single surface has one job: get one idea across at a glance, and reward a closer read.
+
+- Establish a focal point immediately — largest element, most contrast, positioned where the eye
+  lands first.
+- Hierarchy in three levels at most. More reads as noise.
+- Everything aligns to a grid, including the things that look like exceptions.
+- Design for where it will actually be read. A page printed and handed across a table, attached to
+  an email, and projected in a room impose different minimum type sizes, and the one you designed
+  on screen at full width is usually the least representative of the three.
+
+Social graphics, carousels and infographics are a different job with different constraints — the
+feed decides how they are seen. `marketing:visual-content` covers them.
+
+## Never
+
+- Read the slide aloud.
+- Use a chart type because it is interesting rather than because it fits the comparison.
+- Let a template's layout decide your argument's structure.

package/sources/headcount/plugins/product/skills/product-discovery/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: product-discovery
+description: Finds out whether a problem is real and a solution would work, before building it — recruiting the right people, interviewing without leading them, separating what users say from what they do, naming the riskiest assumption and testing that one first, and reaching a decision rather than a summary. Use this to validate a problem, test an idea cheaply, decide whether to build something, or fix a discovery process that keeps confirming what the team already believed.
+---
+
+# Product discovery
+
+Discovery is how you find out you were wrong while it is still cheap. A process that never kills
+anything is not discovery, it is a preparation ritual with research attached.
+
+## Start from the assumption that would sink this if it were false
+
+Every idea rests on a stack: that the problem exists, that people care enough to change what they
+do, that your approach solves it, that they would pay, that you can build and deliver it. They are
+not equally uncertain, and testing them in order of comfort is how teams spend six weeks confirming
+the safe one.
+
+Write the assumptions down, mark the one that would be most damaging to be wrong about, and test
+that one first. Usually it is the second: the problem is real, and people are living with it
+comfortably enough not to move.
+
+## Recruit the people who have the problem, not the people who are easy to reach
+
+Interviewing your friendliest customers produces reliable encouragement. Talk to people who churned,
+people who evaluated and chose something else, and people who solved it another way — those three
+groups carry most of the information.
+
+Five to eight conversations in a segment usually exhausts the new material. If you are still
+hearing new things at eight, the segment is too broad.
+
+## Interview about the past, not about the future
+
+People are poor at predicting their own behavior and generous when asked to react to an idea. They
+are reliable narrators of what they actually did.
+
+- **Ask about the last time it happened.** What triggered it, what they tried, what it cost them,
+  what they did instead.
+- **Follow the workaround.** A spreadsheet someone maintains by hand every week is stronger
+  evidence of a real problem than any amount of enthusiasm about a proposed feature.
+- **Do not describe your solution until the end**, and treat everything said after that point as
+  weaker evidence.
+- **Silence is a tool.** Most of the useful material arrives after the pause you were tempted to
+  fill.
+
+**"Would you use this?" and "would you pay for this?" produce answers that do not predict anything.**
+What predicts is whether they have already spent money or time on the problem.
+
+## Weigh what people do over what they say
+
+Rank evidence honestly: what they have paid for, what they have built themselves, what they do in
+an unprompted usage log, what they say in an interview, what they say in a survey. A prototype
+someone tries in front of you sits high on that list; an enthusiastic reaction to a mockup sits low.
+
+## Test with the cheapest thing that could produce a real signal
+
+Match the artifact to the assumption. Demand risk is testable with a landing page or a sales
+conversation, usability risk with a rough prototype, feasibility with a spike. Building a working
+version to test whether anyone wants it is the expensive way to answer the cheap question.
+
+Define the outcome that would change your mind before you run it. A test with no failing threshold
+is a demonstration.
+
+## End with a decision
+
+Discovery output is build, do not build, or a specific next test — not a deck of themes. Write what
+you learned, what you still do not know, and what you are doing about it, and keep the record of
+the ideas you killed and why. That record is what stops the same idea returning every six months.
+
+## Never
+
+- Test the assumption you are most confident about first.
+- Ask whether someone would use a thing instead of what they did last time it came up.
+- Recruit only from customers who already like you.
+- Run a test with no threshold that would have counted as failure.

package/sources/headcount/plugins/product/skills/product-requirements/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: product-requirements
+description: Writes down what is being built so a team can build it and know when they are done — problem and success measure before solution, scope stated by exclusion, user-visible behavior including the states everyone forgets, acceptance criteria someone can test, and the open questions named rather than buried. Use this to write a specification, review one that is causing rework, or work out why a delivered feature technically matched the request and still was not what anyone wanted.
+---
+
+# Product requirements
+
+A specification exists to prevent expensive rediscovery — of decisions already made, of scope
+already agreed, and of the edge cases that are found either now on a page or later in production.
+
+## Lead with the problem and the number, not the solution
+
+Open with who has the problem, what it costs them today, and what you expect to change if this
+ships — expressed as a measure with a target and a date. A document that starts with a solution
+invites the team to optimize the wrong thing and gives you no way to tell afterward whether it
+worked.
+
+**Decide the success measure before building, not at launch.** A number chosen afterward is chosen
+to be met.
+
+## State scope by exclusion
+
+Everyone reads what is in scope and assumes the rest is coming. An explicit "not in this" list is
+the cheapest thing in the document and prevents most scope arguments — including the ones that
+arrive as clarifications rather than as requests.
+
+Say what is deferred versus what is rejected. Those are different, and conflating them means the
+rejected thing comes back.
+
+## Describe behavior, not implementation
+
+Write what the user experiences and what the system guarantees. Leave the how to the people who
+will own it — a specification that dictates implementation gets a worse implementation and blurs
+who is accountable for it.
+
+**The states nobody writes down are where the rework comes from.** Empty, loading, error,
+partial, permission-denied, offline, and the first-run case with no data. Also: what happens to
+records that already exist, what happens at the limits, and what happens when two people do it at
+once. Most "that wasn't what I meant" traces back to one of these.
+
+## Make acceptance criteria testable
+
+Each one should be a statement someone can evaluate as true or false without asking you. "Fast" and
+"intuitive" are not criteria; a response-time budget and a task someone completes unaided are.
+
+If a criterion cannot be tested, it is either a principle — say so and move it — or it is not
+finished being thought about.
+
+## Name the open questions and who owns them
+
+Every specification has unknowns. Listing them, with an owner and a date needed by, is what
+separates a document that is honestly incomplete from one that is quietly wrong. Buried
+uncertainty gets resolved by whoever hits it first, usually at the least convenient moment and
+without anyone noticing a decision was made.
+
+## Keep it alive, or state that it is frozen
+
+A specification that diverges from what was built becomes a trap for the next person. Either update
+it as decisions change, or mark it as-of-a-date and point at wherever the truth now lives. The
+worst outcome is a document that looks current and is not.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Never
+
+- Open with a solution and leave the problem implied.
+- Ship a specification with no explicit out-of-scope list.
+- Write an acceptance criterion that requires asking you whether it passed.
+- Leave an unresolved question inside the body where it reads as a decision.

package/sources/headcount/plugins/product/skills/product-requirements/references/sources.md

@@ -0,0 +1,67 @@
+# Sources — `product:product-requirements`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## 15 U.S.C. 8403 — Restore Online Shoppers' Confidence Act
+
+US Congress, via the Office of the Law Revision Counsel · US · public domain (US government) — quote freely
+
+<https://uscode.house.gov/view.xhtml?req=granuleid:USC-prelim-title15-section8403&num=0&edition=prelim>
+
+**Authoritative for:** Whether an online auto-renewal offer is lawful — clear disclosure of material terms before billing, express informed consent, and a simple cancellation mechanism. This area has seen rules issued and struck down, so cite the statute rather than a rule summary.
+
+## 36 CFR Part 1194 — Section 508 information and communication technology standards
+
+US Access Board · US · public domain (US government) — quote freely
+
+<https://www.ecfr.gov/current/title-36/subtitle-B/chapter-XI/part-1194>
+
+**Authoritative for:** What a product must satisfy to be lawfully procurable by a US federal agency. This decides a public-sector deal rather than expressing a design preference, which is why it reaches sales as often as engineering.
+
+## Age Appropriate Design Code
+
+UK Information Commissioner's Office · UK · free to use with attribution — credit the publisher
+
+<https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/childrens-information/childrens-code-guidance-and-resources/>
+
+**Authoritative for:** What default settings, nudges and profiling are permissible in a service likely to be used by children. A statutory code, so it settles whether onboarding may default a toggle on.
+
+## California Automatic Renewal Law, Business and Professions Code 17600-17606
+
+California Legislative Counsel · US-CA · public domain — quote freely
+
+<https://leginfo.legislature.ca.gov/faces/codes_displayText.xhtml?division=7.&chapter=1.&part=3.&lawCode=BPC&article=9.>
+
+**Authoritative for:** The concrete cancellation obligations a subscription business actually has to meet, because California's requirements are stricter than the federal floor and apply to any California customer — which in practice makes them the binding ones.
+
+## Children's Online Privacy Protection Rule, 16 CFR 312
+
+US Federal Trade Commission · US · public domain (US government) — quote freely
+
+<https://www.ecfr.gov/current/title-16/chapter-I/subchapter-C/part-312>
+
+Machine-readable: <https://www.ftc.gov/business-guidance/resources/complying-coppa-frequently-asked-questions>
+
+**Authoritative for:** Whether a property counts as directed to children, and therefore whether behavioral advertising, retargeting pixels or lead capture may run on it at all.
+
+## EN 301 549 — accessibility requirements for ICT products and services
+
+ETSI · EU · **read and cite only — copyrighted, do not reproduce**
+
+<https://www.etsi.org/deliver/etsi_en/301500_301599/301549/03.02.01_60/en_301549v030201p.pdf>
+
+**Authoritative for:** The requirement set an EU public-sector buyer measures against, including non-web software, documents and hardware that the web guidelines do not cover. Which version is legally operative depends on what the Official Journal currently cites — check before relying on a newer one.
+
+## Unicode Common Locale Data Repository
+
+Unicode Consortium · global · free to use with attribution — credit the publisher
+
+<https://cldr.unicode.org/>
+
+**Authoritative for:** Correct date, number, currency, name-order, plural and sort behavior for a locale. Settles how something should render in a given language with data rather than guesswork, and every platform's internationalization library derives from it.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/product/skills/ux-product-auditor/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: ux-product-auditor
+description: Audits a website, app, onboarding flow, or design for usability, conversion, and product problems, tying every finding to a business outcome and a severity. Use this to review an interface, diagnose low conversion or activation, find where users drop off, get structured product feedback, or decide which UX fixes to ship first. For raising visual quality rather than finding problems, use `interface-craft`.
+---
+
+# UX and product auditor
+
+A finding that does not name a consequence is an opinion. Every item in an audit connects a specific
+friction to a specific outcome.
+
+## Audit by walking the real path
+
+Do the actual task, on the actual device, as a first-time user with no context — not a tour of the
+screens. Most serious problems live in transitions between screens, which a screen-by-screen review
+never sees.
+
+Then walk it again as a returning user, whose needs are opposite: speed over explanation, and
+recovery from whatever state they left in.
+
+## Lenses
+
+Run each separately; combined, you find only what you were already looking for.
+
+- **Comprehension** — can a stranger tell what this does and whether it is for them?
+- **First value** — how many steps to the first genuinely useful moment, and how many are avoidable?
+- **Friction** — every field, click, decision, and wait. Which are load-bearing and which are
+  habit?
+- **Trust** — does anything ask for more than it has earned at that point?
+- **Recovery** — what happens on error, empty, slow, offline, or wrong input?
+- **Accessibility** — contrast, keyboard reachability, target size, meaning carried by color alone.
+  Below this floor, some people cannot use the product at all.
+
+## Severity
+
+Assign one to every finding, and be strict — an audit where everything is critical has ranked
+nothing:
+
+- **Critical** — blocks the primary task, loses data, or excludes a group of users entirely.
+- **High** — measurably costs conversion or activation for many users.
+- **Medium** — friction with a workaround, or affects a narrower path.
+- **Low** — polish, inconsistency, or a preference.
+
+## Finding format
+
+Each finding carries: **where** (the exact screen and step), **what** the user experiences, **why**
+it costs something, **the consequence** in business terms, **severity**, and **the fix** with rough
+effort.
+
+"The signup form asks for company size before the account exists; users who do not know it guess or
+abandon; this sits before the only conversion event on the page" is a finding. "Form is too long" is
+a note.
+
+## Diagnosing low conversion or activation
+
+Instrument the funnel to find *where*, then observe sessions to find *why*. Analytics say the step;
+only watching says the reason. Teams that skip the second half fix the wrong thing confidently.
+
+Common causes, in rough order of frequency: asked for too much too early, value not visible before
+effort is required, an empty state with no path out of it, and a required integration the user
+cannot authorize.
+
+## Scoring
+
+Where a numeric score is useful — tracking over time, comparing surfaces, reporting to someone who
+did not read the audit — score each lens from one to five against stated criteria, and publish the
+criteria alongside the score. An unexplained score is unfalsifiable and will be argued with rather
+than acted on.
+
+Use the same scale everywhere so scores are comparable between audits. Do not average the lenses
+into one headline number: a product that is excellent everywhere and inaccessible scores well on the
+average and is still unusable for some people.
+
+## Moving from findings to solutions
+
+An audit that stops at problems transfers the hard part back. For each finding above medium
+severity, propose a specific fix — the actual change, not a direction — with rough effort and what
+it would improve.
+
+Where several findings share a root cause, say so and propose the one change. Fifteen findings
+traceable to a missing design system is one finding.
+
+Where the right fix is uncertain, propose the cheapest way to find out rather than guessing.
+
+## Prioritizing
+
+Rank by users affected × severity ÷ effort. Then state the one thing to fix first, and be willing to
+say that most of the list is not worth doing yet. A prioritized audit is more useful than a complete
+one.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Never
+
+- Report a finding without the path that produces it. A claim nobody can reproduce gets ignored.
+- Rank findings by how easy they are to fix. Rank by cost to the user, then note which ones are cheap.
+- Audit a staging build or a marketing page that real users never touch.
+- Call a preference a defect. Say what breaks and for whom, or leave it out.

package/sources/headcount/plugins/product/skills/ux-product-auditor/references/sources.md

@@ -0,0 +1,51 @@
+# Sources — `product:ux-product-auditor`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## 36 CFR Part 1194 — Section 508 information and communication technology standards
+
+US Access Board · US · public domain (US government) — quote freely
+
+<https://www.ecfr.gov/current/title-36/subtitle-B/chapter-XI/part-1194>
+
+**Authoritative for:** What a product must satisfy to be lawfully procurable by a US federal agency. This decides a public-sector deal rather than expressing a design preference, which is why it reaches sales as often as engineering.
+
+## CCPA regulations, California Code of Regulations title 11
+
+California Privacy Protection Agency · US-CA · public domain — quote freely
+
+<https://cppa.ca.gov/regulations/consumer_privacy_act.html>
+
+**Authoritative for:** Symmetry in choice, as law. It settles whether a consent flow where accepting is one click and declining is three is permissible — converting what is usually argued as design taste into a compliance question.
+
+## EN 301 549 — accessibility requirements for ICT products and services
+
+ETSI · EU · **read and cite only — copyrighted, do not reproduce**
+
+<https://www.etsi.org/deliver/etsi_en/301500_301599/301549/03.02.01_60/en_301549v030201p.pdf>
+
+**Authoritative for:** The requirement set an EU public-sector buyer measures against, including non-web software, documents and hardware that the web guidelines do not cover. Which version is legally operative depends on what the Official Journal currently cites — check before relying on a newer one.
+
+## WAI-ARIA and the ARIA Authoring Practices Guide
+
+World Wide Web Consortium · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://www.w3.org/WAI/ARIA/apg/>
+
+Machine-readable: <https://www.w3.org/TR/wai-aria-1.2/>
+
+**Authoritative for:** Which roles, states and keyboard interactions a given widget must implement. Settles whether Escape should close a dialog and whether a role is the right one, without appeal to preference.
+
+## Web Content Accessibility Guidelines 2.2
+
+World Wide Web Consortium · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://www.w3.org/TR/WCAG22/>
+
+**Authoritative for:** Whether a page, email or video is accessible. It is the criteria list that US Section 508, the EU's EN 301 549 and most enterprise procurement point at, so it settles any argument that reaches a buyer's accessibility requirement.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.