@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/luminaries/gary-klein.md

@@ -0,0 +1,166 @@
+---
+tier: lite
+name: Gary Klein
+slug: gary-klein
+claimed_by: [shaper, architect, reviewer, orchestrator]
+referenced_by_skills: [pre-mortem, longrun, build]
+primary_domain: decision-science
+depth: full
+solves_problems_greenfield:
+  - "Team is about to commit to a high-stakes design; risks are hidden in individual heads and hierarchy prevents them from surfacing"
+  - "One-way-door architectural decision needs a structured risk elicitation before commit"
+  - "Security, compliance, or finance scope needs a risk ledger before merge — failure has hard-to-reverse consequences"
+  - "Bet-doc authoring needs a risk ledger before scope commit; retrospective regret is the wrong point to discover the gaps"
+solves_problems_brownfield:
+  - "Team is repeatedly missing failure modes discovered too late in past projects"
+  - "Retrospectives find 'everyone knew but nobody said' patterns — the meeting shape blocks the surface"
+  - "Legacy migration needs risk enumeration before touching the old system that most engineers no longer understand"
+  - "Deploy pipeline changes need a pre-check against past incidents"
+anti_patterns:
+  - "Retrospective blame — running it after failure with names attached; that's a postmortem, and the blame-safe framing collapses"
+  - "Generic risk lists without vivid scenarios — 'the team might be busy' produces no signal"
+  - "Running the pre-mortem too late — after commitment locks in, the write-down produces regret, not mitigation"
+  - "Skipping the silent write-down step — group brainstorming lets the loudest voice anchor the list"
+  - "No follow-through — reasons surface in the meeting and evaporate; named-owner mitigation is required"
+sources:
+  - type: article
+    title: "Performing a Project Premortem"
+    authors: ["Gary Klein"]
+    year: 2007
+    url: "https://hbr.org/2007/09/performing-a-project-premortem"
+    venue: "Harvard Business Review, September 2007"
+    methodology_covered:
+      - "The 4-step pre-mortem procedure — assume failure, silent write-down, round-robin readout, incorporate into plan"
+      - "Prospective hindsight — imagining an outcome has happened increases the ability to identify correct reasons by ~30% (citing Mitchell, Russo, Pennington 1989)"
+  - type: book
+    title: "Sources of Power: How People Make Decisions"
+    authors: ["Gary Klein"]
+    year: 1998
+    url: "https://mitpress.mit.edu/9780262611466/sources-of-power/"
+    isbn: "9780262611466"
+    methodology_covered:
+      - "Recognition-Primed Decision (RPD) model — experts decide by pattern-matching against experience, not by comparing options"
+      - "Naturalistic Decision Making framework"
+  - type: article
+    title: "Conditions for intuitive expertise: A failure to disagree"
+    authors: ["Daniel Kahneman", "Gary Klein"]
+    year: 2009
+    venue: "American Psychologist, 64(6), 515-526"
+    methodology_covered:
+      - "When expert intuition can be trusted and when it cannot — the adversarial-collaboration framework"
+  - type: website
+    title: "Pre-mortems (Shreyas Doshi playbook)"
+    authors: ["Shreyas Doshi"]
+    url: "https://coda.io/@shreyas/pre-mortems"
+    methodology_covered:
+      - "Tigers / Paper Tigers / Elephants lexicon for classifying threats"
+      - "1-hour timebox with named owners on top 3-5 threats"
+  - type: website
+    title: "Use a Pre-Mortem to Identify Project Risks Before They Occur"
+    authors: ["Mike Cohn"]
+    url: "https://www.mountaingoatsoftware.com/blog/use-a-pre-mortem-to-identify-project-risks-before-they-occur"
+    methodology_covered:
+      - "Three-step agile shape — brainstorm, prioritize top 10, assign trigger + mitigation per risk"
+      - "Risk burndown chart alongside sprint retros"
+  - type: website
+    title: "Pre-Mortem tool"
+    url: "https://www.theuncertaintyproject.org/tools/pre-mortem"
+    methodology_covered:
+      - "Seven-step shape with explicit 'no one will argue or object' rule"
+      - "Async survey mode for distributed teams"
+  - type: article
+    title: "Pre-mortem — Technically Working Backwards"
+    url: "https://medium.com/paypal-tech/pre-mortem-technically-working-backwards-1724eafbba02"
+    venue: "PayPal Tech, Medium"
+    methodology_covered:
+      - "Engineering-team adaptation — one-pager (problem + urgency + design + testing) precedes the meeting"
+      - "Multi-team pre-mortems catch architectural misalignment across teams"
+verification_status: verified-with-caveat
+verification_note: "HBR full-text extraction failed at the paywall; the two signature quotes are widely and consistently cited across secondary sources including Kahneman's Thinking, Fast and Slow. The 4-step methodology is consistent across all four operator-provided sources."
+description: "\"Unlike a typical critiquing session, in which project team members are asked what might go wrong, the premortem operates on the assumption that the patient has died, and so asks…"
+---
+
+# Gary Klein
+
+## Signature
+
+*"Unlike a typical critiquing session, in which project team members are asked what might go wrong, the premortem operates on the assumption that the patient has died, and so asks what did go wrong."* — Klein, HBR 2007 [ref:1]
+
+*"Too many people are reluctant to speak up about their reservations during the all-important planning phase."* — Klein, HBR 2007 [ref:1]
+
+Founder of the **Naturalistic Decision Making** field and developer of the **Recognition-Primed Decision** model [ref:2]. Author of *Sources of Power* (MIT Press, 1998) [ref:2] and the *Harvard Business Review* article that introduced the pre-mortem method to broad practice [ref:1]. The bassclef voice on surfacing risks the group knows but the room dynamics suppress.
+
+## Core methods
+
+- **The 4-step pre-mortem procedure** — (1) assume failure vividly ("imagine the project has failed spectacularly"), (2) each person silently writes every reason they can imagine for the failure, (3) round-robin readout with no argument or ranking, (4) incorporate the strongest concerns into the plan as mitigations, monitoring signals, or scope cuts [ref:1].
+- **Prospective hindsight** — imagining an outcome has already happened increases the ability to identify correct reasons for the outcome by roughly 30% versus asking "what could go wrong" [ref:1, citing Mitchell, Russo, Pennington 1989].
+- **Blame-safe elicitation** — no argument during readout; concerns are gifts, not attacks. The room dynamics that would suppress dissent in a normal planning meeting are structurally removed.
+- **Lens rotation** — running the pre-mortem through multiple perspectives (customer, engineer, ops, legal, finance) surfaces risks that any single lens would miss. Doshi's Tigers/Elephants classification and PayPal Tech's per-team runs both instantiate this shape [ref:4, ref:7].
+
+## When to channel this luminary
+
+Fire at any high-stakes scope-commit boundary. Bassclef applications:
+
+- Bet-doc authoring — the risk ledger IS a pre-mortem output
+- `/longrun` scope-shape pick — before committing to which shape
+- Any change that touches security, authentication, compliance, payments, or user-lifecycle-critical paths
+- Architectural decisions with hard-to-reverse consequences
+- Deploy pipeline edits
+- Adopter-observable API surface changes
+
+INSTEAD of running Klein's pre-mortem for trivial low-cost work — the method has a real cost (60-90 minutes) and produces low signal on decisions that can be reversed cheaply. Reserve for one-way-door scope.
+
+## Stack translation
+
+In a bassclef bet doc:
+
+- The `## Risk ledger (pre-mortem)` section IS the artifact
+- Each rotated lens is a `@luminary` primary or supporting citation — Feathers for characterization coverage, Ousterhout for interface complexity, Nygard for stability patterns, Beck for TDD, Saltzer-Schroeder for security-adjacent scope
+- Each identified risk gets an owner (which WU addresses it) and a mitigation (concrete fix)
+- The `## Compounding sequence` per shape borrows from Doshi's "top 3-5 threats named" cadence
+
+In an operator session:
+
+- `/pre-mortem <scope>` (ship in bet 2026-07-07a) walks the 4 steps and produces `docs/risk-ledgers/<slug>.md`
+- Always-fire domains: authentication, authorization, schema migrations with backfills, payments and billing, PII handling, multi-tenant boundaries, public marketing claims, user-lifecycle flows (account create/delete/password), deploy pipeline changes, third-party integrations, and compliance-scoped work (GDPR/HIPAA/SOC 2/PCI DSS)
+
+## Anti-patterns it prevents
+
+- **Retrospective blame** — running the exercise after failure with names attached collapses the blame-safe framing. Klein's discipline: run BEFORE the failure, so concerns are gifts about a hypothetical future.
+- **Generic risk lists** — "the team might be busy" produces no mitigation because it does not describe a specific failure. Klein's discipline: imagine failure vividly. "The migration ran during the holiday freeze and locked the payments table for 3 hours" is actionable.
+- **Skipping silent write-down** — group brainstorming lets the loudest voice anchor the list. Klein's silent step is load-bearing; without it, the pre-mortem regresses to a normal planning meeting.
+- **Meeting-then-forget** — reasons surface and evaporate. Doshi's follow-up discipline (named owners + mitigation trigger per risk) is what makes pre-mortem produce compounding value.
+
+## Worked example (bassclef application)
+
+Bet 30b risk ledger at `docs/risk-ledgers/2026-06-30b-substrate-anchoring-cure.md` is a live bassclef pre-mortem. The bet author (working alone) rotated through 8 luminary lenses (each representing a distinct failure class) and produced concrete mitigations tied to specific WUs. The output shape:
+
+- **Lens-by-lens risk enumeration** — Feathers surfaces "cure ships without characterization test"; Ousterhout surfaces "shared lib duplicates existing helper"; Beck surfaces "Tier 0 test written after source"; etc.
+- **Per-risk owner and mitigation** — each risk names the WU that addresses it and the concrete change (e.g., "WU-E adds Tier 0 test at write-time; RED confirmed via `bash <test> && [ $? -eq 1 ]`")
+- **Retrospective feedback loop** — the closeout chronicle checks whether each pre-mortem risk actually materialized and whether the mitigation held
+
+The bassclef pattern extends Klein's original 4-step meeting into a written artifact that the operator can review async and re-consult during execution.
+
+## Sources
+
+1. Klein, G. (2007). "Performing a Project Premortem." *Harvard Business Review*, September 2007. https://hbr.org/2007/09/performing-a-project-premortem [ref:1]
+2. Klein, G. (1998). *Sources of Power: How People Make Decisions.* MIT Press. ISBN 9780262611466 [ref:2]
+3. Kahneman, D., & Klein, G. (2009). "Conditions for intuitive expertise: A failure to disagree." *American Psychologist*, 64(6), 515-526 [ref:3]
+4. Doshi, S. Pre-mortems playbook. https://coda.io/@shreyas/pre-mortems [ref:4]
+5. Cohn, M. "Use a Pre-Mortem to Identify Project Risks Before They Occur." https://www.mountaingoatsoftware.com/blog/use-a-pre-mortem-to-identify-project-risks-before-they-occur [ref:5]
+6. The Uncertainty Project. Pre-Mortem tool. https://www.theuncertaintyproject.org/tools/pre-mortem [ref:6]
+7. PayPal Tech. "Pre-mortem — Technically Working Backwards." https://medium.com/paypal-tech/pre-mortem-technically-working-backwards-1724eafbba02 [ref:7]
+8. Mitchell, D., Russo, J., Pennington, N. (1989). "Back to the future: Temporal perspective in the explanation of events." *Journal of Behavioral Decision Making* — cited in the HBR piece as the ~30% prospective-hindsight lift
+
+## Related luminaries
+
+- **Daniel Kahneman** — planning fallacy, System 1/2, and the adversarial-collaboration partner (2009 paper). Pre-mortem is one direct application of Kahneman's finding that people plan too optimistically.
+- **Paul Slovic** — risk perception and the affect heuristic; foundational to the naturalistic-decision-making tradition Klein extends.
+- **Amos Tversky** — heuristics and biases; the tradition Klein both extends and pushes back against (Klein argues expertise can be trusted where general heuristics fail).
+- **Herbert Simon** — bounded rationality; the RPD model is Simon's satisficing applied to expert decision-making.
+- **Karl Weick** — sensemaking in high-reliability organizations; sibling to naturalistic decision-making.
+- **Michael Feathers** — characterization tests as the code-side analog: pin what the system does before changing it, just as Klein's pre-mortem pins what could go wrong before shipping.
+
+## Substrate-as-system anchor (bassclef)
+
+Klein's pre-mortem anchors bet 2026-07-07a's `/pre-mortem` skill (ticket #655). The skill produces `docs/risk-ledgers/<slug>.md` — a written pre-mortem artifact — and is always-fire for the domain list documented in `docs/operator-questions/2026-07-07-longrun-open-questions.md` Q2. Klein's blame-safe silent-write-down + round-robin shape maps naturally to a solo-operator + Claude conversational shape: Claude prompts each lens; operator writes each concern; Claude collates without ranking during the pass; then a follow-up pass names owners and mitigations. The 4-step shape is preserved even when the "team" is one operator plus multiple luminary lenses summoned in sequence.

package/dist/lite/.claude/luminaries/kaoru-ishikawa.md

@@ -0,0 +1,162 @@
+---
+tier: lite
+name: Kaoru Ishikawa
+slug: kaoru-ishikawa
+claimed_by: [builder, architect, closer]
+primary_domain: engineering
+depth: full
+description: "\"Before you fix the cause, name every category it could live in.\""
+---
+
+# Kaoru Ishikawa
+
+## Signature
+
+*"Before you fix the cause, name every category it could live in."*
+
+Kaoru Ishikawa (1915–1989) was a Tokyo University engineering professor
+who created the **fishbone diagram** in 1968 — a tool that forces an
+investigator to enumerate categories of possible cause before picking
+which one to chase. He named six default categories (Method, Machine,
+Material, Man, Measurement, Environment — the **6M**) so any team can
+start from the same starting set rather than guessing what to look at
+first. He also pioneered **quality circles** at Kawasaki Steel in 1962,
+where shop-floor workers themselves ran the diagnosis loop on the
+problems they could see better than any manager.
+
+## Core methods
+
+- **Fishbone diagram (Ishikawa diagram)** — draw the problem on the
+  right as the fish head; draw a horizontal spine; branch six diagonal
+  bones for the 6M categories. Fill each bone with contributing causes.
+  Use when the problem has more than one likely cause OR the team is
+  about to default to the most familiar cause without checking the rest.
+- **6M categorization** — Method (how we do the work), Machine (tools
+  and systems), Material (inputs we depend on), Man (people, roles,
+  training), Measurement (what we count and how), Environment (context
+  the work runs in). Adapt the six to the domain when needed (software:
+  Methods, Tools, Data, People, Metrics, Context).
+- **Quality circles** — small groups of people closest to the work meet
+  weekly, pick one problem, run the diagnosis, propose the fix. The
+  people who see the problem are the people who fix it. The discipline
+  is the regular cadence, not the size of the group.
+- **Seven basic tools of quality** — fishbone, Pareto, check sheet,
+  control chart, histogram, scatter plot, flowchart. Ishikawa argued
+  any plant worker could be trained on all seven in a week and that
+  most quality problems yield to just these tools, no statistician
+  required.
+
+## When to channel this luminary
+
+Channel Ishikawa when the failure has multiple visible contributors and
+the team is about to fix the most familiar one. Specifically: when the
+agent is choosing between competing remediations (a / b / c framings),
+when a single session surfaces three or more substrate defects of
+different shapes, when an audit is starting and the question is "what
+categories of defect do we expect to find," or when a chronicle starts
+to read like a list of unrelated incidents that probably share a deeper
+class.
+
+Fishbone is the diagnostic move BEFORE the five-whys move. Five-whys
+goes deep on one chain. Fishbone goes broad across categories first,
+then five-whys picks the chain worth going deep on.
+
+## Stack translation
+
+Bassclef's substrate is the production system Ishikawa would analyze.
+The 6M maps cleanly to bassclef surfaces:
+
+- **Method** — the discipline rules in `.claude/rules/`, the procedures
+  in skill bodies, the gate cascades the operator runs by hand
+- **Machine** — the hooks in `.claude/hooks/`, the validators, the
+  state-spine accessors, the harness itself
+- **Material** — `substrate.config.md`, schemas in
+  `standards/state-spine/schemas/`, the source data the validators read
+- **Man** — the operator, Claude Code agents, adopter agents downstream
+- **Measurement** — gate-compliance counters, chronicle Gate Evidence
+  tables, marker counts in `state/markers/`
+- **Environment** — the harness session lifecycle, the file-system
+  state, the network reachability for `gh` and `git fetch`
+
+When a substrate defect surfaces, draw the fishbone before picking a
+fix. The substrate.config.md missing-field gate that fired tonight is a
+Material defect (the file is the input, the field is missing). The
+unwired hooks are a Machine defect (the hooks exist but the wiring
+plumbing dropped them). The validator-without-bootstrap is a Method
+defect (the hardening shipped without the bootstrap row that the method
+required). These are three categories, three classes, three remediation
+paths — not one bug to patch.
+
+## Anti-patterns it prevents
+
+- **Narrow-fix default** — Without the fishbone categorization, the
+  agent picks the smallest visible fix and ships. Three sessions later
+  the same class of defect surfaces in a different category and the
+  operator carries the cost of re-diagnosing what was actually one
+  class of problem all along.
+- **Cause-of-the-week** — Without the 6M anchor, every postmortem picks
+  whichever category was most recently in mind. Last week it was
+  Material (config files); this week it's Machine (hooks); next week
+  someone decides it's really Method (people not following rules). The
+  diagnosis bounces.
+- **Single-author root-cause** — Without quality-circle discipline, the
+  diagnosis comes from whoever happens to be in the chair. Ishikawa's
+  insight: the operator running daily sees patterns the architect
+  doesn't. Bassclef's discipline-gate cascade where the operator
+  surfaces defects mid-session is the bassclef analog of the quality
+  circle.
+
+## Worked example
+
+PR #1371 CI failure on public bassclef (2026-06-24). Surface symptom:
+one test references a script not shipped to public. The agent's first
+framing was (a) narrow fix / (b) pause + audit / (c) investigate origin.
+That framing is the cause-of-the-week trap: a is Material (mark test
+`tier: upstream`), b is Method (run the audit first), c is Machine
+(figure out where the 30 public-only scripts came from). The operator
+sensing the framing was off is the quality-circle signal.
+
+Applied fishbone to the symptom "release pipeline produces failing
+public CI":
+
+- **Method** — `release-to-bassclef.sh` ALLOWED_PATHS rule was added
+  without a parallel discipline for "what already lives on public"
+- **Machine** — the release script `rsync --delete`s the public tree
+  for paths it ships; the rule "we do not break adopters" has no
+  mechanical guard at that surface
+- **Material** — 30+ public-only scripts of unknown origin (apply-
+  migration.sh, install.sh, bind-subdomain.sh) — likely vestiges of the
+  pre-rename canonical-public era
+- **Man** — single operator + agents; no quality-circle review of the
+  public bassclef tree's origin since the canonical→bassclef rename
+- **Measurement** — no count of "files on public that do not exist on
+  bassclef-upstream" anywhere; the defect is invisible until /release
+  fires
+- **Environment** — closed beta has not opened; cheapest possible
+  window to harden before any external adopter depends on those
+  scripts
+
+Across all six categories, the deeper class is clear: public bassclef
+holds files of unknown provenance because the canonical→bassclef rename
+treated the public tree as a destination, not a source-to-reconcile.
+That is the root class. Three of the four 2026-06-24 substrate defects
+trace back to the same class. /architect-review at #320 reads as the
+right next move.
+
+## Sources
+
+- *Guide to Quality Control* — Ishikawa (1968; English 1976)
+- *What Is Total Quality Control? The Japanese Way* — Ishikawa (1985)
+- *Introduction to Quality Control* — Ishikawa (1990)
+
+## Related luminaries
+
+- **Taiichi Ohno** — Five Whys goes deep on one chain; Ishikawa's
+  fishbone goes broad across categories first. Use Ishikawa then Ohno.
+- **W. Edwards Deming** — PDCA cycle closes the diagnosis loop; PDCA
+  needs a category to act on, which is what fishbone delivers.
+- **Kepner-Tregoe** — Is/Is Not narrows the scope of what is affected
+  before fishbone categorizes possible causes. Use KT then Ishikawa
+  then Ohno.
+- **Joseph Juran** — Pareto principle on causes (80/20); after
+  fishbone surfaces categories, Pareto picks which one to chase first.

package/dist/lite/.claude/luminaries/lean-product-canvas.md

@@ -0,0 +1,33 @@
+---
+tier: lite
+name: Lean Product Canvas
+slug: lean-product-canvas
+claimed_by: [product-manager]
+primary_domain: product
+depth: stub
+description: "\"If you can't fill it in 30 minutes, you don't understand the problem.\""
+---
+
+# Lean Product Canvas (Dan Olsen)
+
+## Signature
+
+*"If you can't fill it in 30 minutes, you don't understand the problem."*
+
+One-page product planning canvas from Dan Olsen (*The Lean Product
+Playbook*). Forces concise articulation of target customer, problem,
+value proposition, feature set, and UX.
+
+## Core methods
+
+- **Problem Space vs Solution Space** — clearly separate the two;
+  ideate on problem first, converge on solution second.
+- **Product-Market Fit Pyramid** — target customer → needs → value
+  prop → feature set → UX. Each level supports the next.
+- **Hypothesis-driven product** — treat canvas assumptions as
+  hypotheses to test, not decisions to commit to.
+
+## Sources
+
+- *The Lean Product Playbook* — Olsen (2015)
+- leanproductplaybook.com

package/dist/lite/.claude/luminaries/luke-wroblewski.md

@@ -0,0 +1,224 @@
+---
+tier: lite
+name: Luke Wroblewski
+slug: luke-wroblewski
+claimed_by: [designer]
+referenced_by_skills: [frontend-design, prototype-variants, visual-review]
+primary_domain: ux
+depth: full
+agent_drafted: 2026-05-06
+operator_review_pending: true
+verification_status: verified
+sources:
+  - type: book
+    title: "Mobile First"
+    authors: ["Luke Wroblewski"]
+    year: 2011
+    isbn: "978-1937557096"
+    url: "https://abookapart.com/products/mobile-first"
+    methodology_covered: ["Mobile first principle", "thumb zones", "progressive enhancement"]
+  - type: book
+    title: "Web Form Design: Filling in the Blanks"
+    authors: ["Luke Wroblewski"]
+    year: 2008
+    isbn: "978-1933820224"
+    url: "https://rosenfeldmedia.com/books/web-form-design/"
+    methodology_covered: ["input reduction", "progressive disclosure in forms", "inline validation", "form field design patterns"]
+  - type: website
+    title: "LukeW.com — Ideation + Creation"
+    authors: ["Luke Wroblewski"]
+    url: "https://www.lukew.com"
+    methodology_covered: ["ongoing mobile + form design research and essays"]
+solves_problems_brownfield:
+  - "Existing form has many fields and abandonment is high"
+  - "Mobile experience is desktop-first squeezed into small screens"
+  - "Input types, validation, and progressive disclosure aren't optimized for thumbs"
+  - "Forms ask for data the user has already provided or the system can infer"
+solves_problems_greenfield:
+  - "Designing a mobile-first product where forms are core to the value"
+  - "Planning input surfaces where progressive disclosure must be designed from the start"
+  - "Building for mobile users where thumb-zone economy matters"
+  - "Designing form flows where staged input (now / later / never-asked) is a first-class concern"
+anti_patterns:
+  - "Read-only data display — Wroblewski is for input"
+  - "Desktop-power-tool surfaces where mobile isn't primary"
+  - "Quick utilities where forms are minimal"
+description: "\"Mobile first forces you to focus on what matters.\""
+---
+
+# Luke Wroblewski
+
+## Signature
+
+*"Mobile first forces you to focus on what matters."*
+
+Author of *Mobile First* (2011) and *Web Form Design: Filling in the Blanks* (2008). Product Director at Google; previously co-founded Bagcheck (acquired by Twitter); led design at Yahoo + eBay. The voice for **mobile-first, touch-first, constraint-led interaction design** — using mobile's constraints as a forcing function for clarity.
+
+Wroblewski's signature contribution is **mobile-first as discipline** (not as squeeze) — designing for the most constrained context (small screen, touch input, variable network, divided attention) FIRST, then progressively enhancing for less-constrained contexts. The constraints expose what's essential; less-essential elements naturally get cut.
+
+For canonical, Wroblewski is the form-design + mobile-discipline luminary. Where Friedman is the broader pattern catalog and Krug is the comprehension discipline, Wroblewski is the specific authority on input surfaces + mobile-first thinking.
+
+## Sources
+
+- *Mobile First* — Wroblewski, A Book Apart (2011) — primary
+- *Web Form Design: Filling in the Blanks* — Wroblewski, Rosenfeld Media (2008) — primary
+- [lukew.com](https://lukew.com) — primary site, ongoing essays + research
+- *Funnel: How Forms Convert* — research project (lukew.com/funnel)
+- Google's mobile + form design teams influenced by Wroblewski's discipline (he leads them now)
+
+## Core methods
+
+- **Mobile first** — Design for the most constrained context first: [ref:1]
+  - Small screen → forces priority (what's essential?)
+  - Touch input → forces gesture-friendly affordances
+  - Variable network → forces lean payloads + offline-first
+  - Divided attention → forces clarity + scannability
+  - Larger screens are progressive enhancement; the mobile design is the truth
+
+- **Thumb zones** — Physical-reach analysis of mobile devices: [ref:1]
+  - Bottom-center is most reachable (one-handed)
+  - Bottom-corners are reachable but uncomfortable
+  - Top of screen is hard-reach; reserve for non-primary
+  - Primary actions in thumb-reachable zone; chrome / less-frequent actions higher
+
+- **Input reduction** — Every form field is friction: [ref:2]
+  - Audit every field: required? Why? Could the system infer it?
+  - Required fields: minimum count; explain why each is needed
+  - Optional fields: collect later if at all
+  - Pre-fill from sensors / context / user history wherever possible
+
+- **Progressive disclosure** — Stage input over time:
+  - Now (essential to start)
+  - Later (when needed, contextually)
+  - Never-asked (the system infers or doesn't need)
+
+- **Input type discipline** — Use HTML5 input types correctly:
+  - `type="email"` for email; triggers email keyboard
+  - `type="tel"` for phone; triggers number pad
+  - `type="number"` for quantities; triggers number keyboard
+  - `type="date"` for dates; triggers date picker
+  - Type discipline reduces friction substantially on mobile
+
+- **Inline validation** — Validation on field-blur or after-typing-stops; not at submit
+- **Form layout** — One column; labels above; touch-target sized inputs
+- **Top of forms** — Don't show legal text / policy / context here; dive straight to inputs; legal at bottom or behind link
+
+## INSTEAD-block discipline
+
+| Anti-pattern | INSTEAD |
+|---|---|
+| Desktop-first design squeezed for mobile | Mobile-first; design for small screen first; larger is progressive enhancement |
+| Form with 12+ fields | Audit ruthlessly; minimum fields to enable the user's task; defer or infer the rest |
+| Labels beside inputs | Labels ABOVE inputs (mobile + desktop); easier to scan; works with screen readers |
+| Multi-column form layout on mobile | One column; tap target accessibility; users scroll vertically anyway |
+| Generic `<input type="text">` for everything | Use HTML5 input types: `email`, `tel`, `number`, `date`, etc.; right keyboard on mobile |
+| Validation on submit only | Inline validation on field-blur; clear error messages; don't punish until submit-time |
+| Touch targets sized for cursor (28-32px) | Touch targets ≥ 44x44px (iOS) / 48x48dp (Android); thumb-friendly |
+| Required and optional fields visually identical | Mark optional explicitly ("Phone number (optional)"); reduces cognitive load |
+| Long forms as one screen | Multi-step with progress indicator; chunks respect working memory; user feels progress |
+| Top-of-form filled with legal/policy text | Top of form: dive straight to inputs; legal at bottom or behind link |
+| "Sign up to continue" before user explores | Soft-lock: try the product, sign up when value is felt; reduces sign-up friction at value-discovery moment |
+| Inferring nothing; asking for everything | Sensors + context + user history pre-fill: location from GPS, name from device-account, history from previous-fields |
+| Mobile-only navigation hidden in hamburger | Critical actions visible by default; secondary in hamburger; hamburger should be #2 not #1 |
+| Capturing data the system can derive | Don't ask date if creation-time is the answer; don't ask city if GPS or postal-code reveals; pre-fill |
+
+## When to channel this luminary
+
+- Always — when designing or auditing forms or any input-heavy surface
+- Especially — when the product is mobile-first / touch-first; Wroblewski's discipline is mandatory there
+- Pair with `vitaly-friedman` (broader pattern catalog) — Friedman + Wroblewski compose: Friedman's general patterns + Wroblewski's form/mobile depth
+- Pair with `bj-fogg` (behavior model) — Wroblewski's input-reduction reduces required ABILITY (Fogg's lever); pair for behavior + form design
+
+Do NOT use this luminary alone for read-only data display, desktop-power-tool surfaces, or quick utilities where forms are minimal.
+
+## Stack translation
+
+In React + Tailwind + accessible primitives:
+
+- **Mobile-first CSS** → Tailwind's mobile-first utilities default; `md:` and `lg:` are progressive enhancement
+- **Thumb zones** → Primary mobile actions (`<BottomActionBar>`) at bottom; chrome (logo, secondary nav) at top; hamburger only for tertiary
+- **Form layout** → Single column always; labels above inputs (`<Label>` rendered before `<Input>` semantically + visually); generous spacing between fields
+- **Input types** → HTML5 type attribute precise per field semantic: `email`, `tel`, `number`, `date`, `url`, etc.
+- **Touch targets** → `min-h-[44px]` on all interactive elements (mobile); `<Button>` component enforces minimum
+- **Inline validation** → `useFormState` or React Hook Form; validation on blur; error displayed below field with plain language
+- **Progressive disclosure** → Multi-step forms with `<Wizard>` component; progress indicator visible; back-step always available
+- **Optional field marking** → `(optional)` suffix on label OR distinct visual treatment for required vs optional
+- **Input pre-fill** → `useUserContext()` / `useDevice()` hooks pre-fill known values; user can override
+- **Sensor input** → Camera scan, geolocation, biometric where appropriate; reduce typing on mobile
+- **Lean payloads** → Mobile-aware loading; defer non-critical assets; `loading="lazy"` images
+- **Audit script** → `/visual-qa` includes mobile-specific checklist: thumb-zone, touch-targets, input-types, inline-validation, lean-payload
+
+## Anti-patterns it prevents
+
+- **Desktop-first squeeze** — designed for desktop, mobile is afterthought; mobile experience suffers
+- **Form-as-friction** — long forms with default text inputs; mobile users abandon
+- **Tap-target small** — 32px buttons; mobile users miss; frustrate
+- **No input-type discipline** — generic `<input>` everywhere; wrong keyboard on mobile; friction
+- **Submit-time validation** — user fills form, hits submit, sees 5 errors; rage; abandon
+- **Cognitive-load form** — required + optional fields visually identical; user uncertain; abandon
+- **Pre-fill skipped** — system has data, asks anyway; user types what's already known
+- **Top-of-form legal** — user has to scroll past policy; gives up at "by signing up..." paragraph
+
+## Worked example
+
+For canonical's hypothetical mobile sign-up flow:
+
+Wroblewski's prescription:
+
+**Mobile-first design**:
+- Single column; labels above inputs; generous spacing
+- 4 fields total: email + name + repo-URL + create-button
+- Below: "Why we ask for these" disclosure (legal at bottom, behind link)
+
+**Input discipline**:
+- Email: `type="email"` (email keyboard) + inline domain validation
+- Name: pre-fill from device account (Google / Apple / etc.) if signed in
+- Repo-URL: paste-from-clipboard hint visible (mobile users often paste); accepts GitHub URL or `owner/repo`
+- Create button: full-width; `min-h-[48px]`; placed in thumb-reachable zone
+
+**Progressive disclosure**:
+- Sign-up = email + repo-URL ONLY (2 fields)
+- After first session: "want to add your name? optional"
+- Advanced settings (auth tokens, deploy targets): never-asked; configured later when needed
+
+**Inline validation**:
+- Email: validates on blur; "looks like a valid email" or "domain looks unfinished"
+- Repo-URL: validates on blur; checks "github.com" reachability; suggests format if user typed something off
+
+**Pre-fill**:
+- If user is on a phone with active GitHub session: pre-fill email + name
+- If user is on canonical-installed device: pre-fill from device's user
+
+**Form payload (mobile-aware)**:
+- Form HTML + minimal JS bundle; no analytics-blocking client-side; loads on slow connection in <2s
+- After submit, optimistic UI ("setting up your repo...") + actual work async
+
+What this luminary catches that "make a sign-up form" misses: the field-count discipline (4 not 12), the input-type precision, the pre-fill from context, the progressive disclosure (2 fields now, more later), the thumb-zone-button placement, the inline validation pattern.
+
+## How to use in canonical's chain
+
+In `/visual-review`:
+- Form audit per Wroblewski rubric: field count, label position, input types, thumb zones, inline validation
+- Mobile-specific audit category required for mobile-targeting surfaces
+
+In `/visual-qa`:
+- Mobile interactive testing per Wroblewski; thumb-zone reach + touch targets + input keyboards verified
+- Form-completion timing measured; abandonment points identified
+
+In `/riff-prototypes`:
+- Mobile-first variants explicitly use Wroblewski's discipline as primary
+- Champion-challenger against desktop-first variants if both modes target
+
+In `/frontend-design`:
+- Wroblewski's principles as input-surface defaults
+- Form components in design system follow Wroblewski-shaped patterns
+
+## Related luminaries
+
+- **Vitaly Friedman** — Broader pattern catalog; Friedman + Wroblewski compose for forms + mobile
+- **Steve Krug** — Don't make me think; Krug + Wroblewski share the input-reduction discipline
+- **BJ Fogg** — Behavior model; Wroblewski's input-reduction lowers ability cost (Fogg's primary lever)
+- **Susan Weinschenk** — Cognitive science; Weinschenk's working memory limits inform Wroblewski's progressive disclosure
+- **Apple HIG** — Mobile platform conventions; HIG + Wroblewski align on touch-target sizes + thumb zones
+- **Google Material Design** — Form components + mobile patterns; Material's primitives implement Wroblewski's principles
+- **Aarron Walter** — Microcopy; Walter's voice + Wroblewski's structure compose for delightful forms