@schilling.mark.a/software-methodology 1.0.0

package/ux-design/references/usability-evaluation.md

@@ -0,0 +1,132 @@
+# Usability Evaluation
+
+## What Is a Usability Evaluation?
+
+A structured review of a planned experience against established usability principles. Run it BEFORE screen flows are designed — catching problems at this stage costs nothing. Catching them after implementation costs a full redesign cycle.
+
+This is not a visual design review. It is a behavioral review: Will users be able to accomplish their goals? Where will they get stuck? Where will they make mistakes?
+
+## The 10 Heuristics
+
+These are the evaluation criteria. For each planned screen or flow, check against all 10. Document any violations found.
+
+### H1: Visibility of System Status
+The product always keeps users informed about what is going on, through appropriate feedback within reasonable time.
+
+**Check:** Does every action produce visible feedback? Does the user always know what state they're in? Is loading always indicated? Is the current location in the navigation always clear?
+
+### H2: Match Between System and Real World
+The product speaks the user's language — words, phrases, concepts familiar to the user. Information appears in a natural and logical order.
+
+**Check:** Do all labels match the mental model vocabulary? Are navigation categories organized the way the user thinks about the domain? Do action labels describe the outcome, not the system operation?
+
+### H3: User Control and Freedom
+Users often choose system functions by mistake and need a clearly marked "emergency exit" to leave the unwanted state without having to go through a long procedure.
+
+**Check:** Can the user undo every action? Is Cancel always available alongside Save? Can the user close or dismiss any modal, drawer, or overlay? Is there a way back from every dead end?
+
+### H4: Consistency and Standards
+Users should not have to wonder whether different words, situations, or actions mean the same thing. Follow platform conventions.
+
+**Check:** Do all buttons of the same type look and behave identically? Do all forms validate the same way? Do all error messages follow the same structure? Does terminology stay consistent across all screens?
+
+### H5: Error Prevention
+Even better than good error messages is careful design that prevents problems from occurring in the first place.
+
+**Check:** Are required fields clearly marked before the user submits? Are invalid options removed or disabled rather than shown and then rejected? Does the system warn before destructive actions? Are ambiguous actions clarified before execution?
+
+### H6: Recognition Rather Than Recall
+Minimize the user's memory load by making objects, actions, and options visible. The user should not have to remember information from one part of the interface to use another.
+
+**Check:** Are options visible rather than requiring the user to recall them? Are defaults sensible? Is context preserved when navigating between screens? Are labels and instructions visible at the point of use, not hidden in a help page?
+
+### H7: Flexibility and Efficiency of Use
+Accelerators — unseen by the novice user — may often speed up interaction for expert users. The system should cater to both inexperienced and experienced users.
+
+**Check:** Can expert users accomplish tasks faster (keyboard shortcuts, bulk actions, saved filters)? Does the default flow serve novice users without requiring them to know shortcuts? Are frequently used actions accessible without deep navigation?
+
+### H8: Aesthetic and Minimalist Design
+Dialogues should not contain irrelevant or rarely needed information. Every extra unit of information competes with relevant information and diminishes their relative visibility.
+
+**Check:** Does every screen contain only information needed for the current task? Are there elements that exist for decoration rather than function? Can any screen be simplified without losing necessary capability?
+
+### H9: Help Users Recognize, Diagnose, and Recover from Errors
+Error messages should be expressed in plain language (not codes), precisely indicate the problem, and constructively suggest a solution.
+
+**Check:** Do all error messages explain what went wrong in plain language? Do they suggest what to do next? Do they preserve the user's work? Is there a path forward from every error state? (See interaction-patterns.md Error Recovery for detail.)
+
+### H10: Help and Documentation
+Even though it is better if the system can be used without documentation, it may be necessary to provide help that is easy to search and focused on the user's task.
+
+**Check:** Is the product usable without documentation for the primary persona's primary goal? Where help IS needed, is it contextual (at the point of use) rather than requiring the user to leave the task to find it? Are tooltips or inline explanations present for non-obvious controls?
+
+## Severity Scoring
+
+Each violation found gets a severity score. This determines priority.
+
+| Score | Severity | Meaning |
+|---|---|---|
+| 0 | Not a problem | Evaluated but no usability issue exists |
+| 1 | Cosmetic | Problem occurs but does not affect task completion |
+| 2 | Minor | Occasional usability problem, workaround exists |
+| 3 | Major | Usability problem, no obvious workaround, task completion is impaired |
+| 4 | Catastrophic | Users cannot accomplish the task at all |
+
+**Priority rule:**
+- Score 4: Must fix before any screen is designed. Redesign the flow.
+- Score 3: Must fix before implementation begins.
+- Score 2: Fix before shipping. Can be addressed during design phase.
+- Score 1: Fix if time permits. Does not block.
+
+## Evaluation Report Format
+
+Create: `/docs/ux-design/usability-evaluation/[feature-name].md`
+
+```markdown
+# Usability Evaluation: [Feature Name]
+
+**Evaluated:** [Date]
+**Personas evaluated for:** [List of personas]
+**Scenarios evaluated:** [List of feature file scenarios]
+**Evaluated by:** [Claude / team member]
+
+## Summary
+[1–2 sentences: overall usability health of this feature's planned experience.
+How many violations found, how many are critical.]
+
+## Violations Found
+
+### [Violation Title]
+- **Heuristic:** H[N] — [Heuristic name]
+- **Severity:** [0–4]
+- **Location:** [Which screen or flow step]
+- **Description:** [What the problem is — specific, not generic]
+- **Impact:** [What happens to the user if this isn't fixed]
+- **Recommendation:** [Specific fix — not "make it better" but "change X to Y"]
+
+### [Next Violation]
+[Same structure]
+
+---
+
+## Violations by Severity
+
+| Severity | Count | Violations |
+|---|---|---|
+| 4 — Catastrophic | [N] | [titles] |
+| 3 — Major | [N] | [titles] |
+| 2 — Minor | [N] | [titles] |
+| 1 — Cosmetic | [N] | [titles] |
+
+## Clearance
+
+- [ ] All severity 4 violations resolved — redesign before proceeding
+- [ ] All severity 3 violations resolved — cleared for ui-design-workflow
+```
+
+## Rules
+
+- Run evaluation after scenarios are written but before screen flows are designed
+- Evaluate for the primary persona first. Then check if secondary personas can accomplish their goals with the same design
+- A severity 4 violation means the planned flow must change. Do not proceed to screen design until it is resolved
+- Document the evaluation even if no violations are found — it proves the design was checked

package/ux-research/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ux-research
+description: User experience research skill for defining personas, mental models, and user journey maps before product development begins. Use when starting a new product or feature set, when defining who the users are, when the user says "who are our users", "define personas", "map the user journey", or "understand our customers". Reads and updates the Value Proposition Canvas and Business Model Canvas. Output feeds directly into story-mapping skill — personas and journeys determine which activities and tasks exist.
+---
+
+# UX Research
+
+## Overview
+
+Discovery before design. Defines who the users are, how they think, what they currently do, and where they struggle. Every downstream decision — story maps, scenarios, screen flows — is grounded in this research. Without it, you are guessing.
+
+## When to Run This Skill
+
+- **New product:** Run fully before any story mapping begins
+- **New feature set:** Run a focused version scoping only the affected user segment and journey
+- **Existing product, new user segment:** Run personas and journey mapping for the new segment only
+
+## Workflow
+
+### Step 1: Define Personas
+
+Personas are the cast of characters the product serves. Every subsequent design decision is made "for" a specific persona.
+
+See `references/personas.md` for structure, how to derive them from the Value Proposition Canvas, and the file format.
+
+Create: `/docs/ux-research/personas/[persona-name].md`
+
+### Step 2: Map Mental Models
+
+Mental models capture how each persona *thinks* about the problem domain — not how the system works, but how the user conceptualizes it. Designs that match mental models feel intuitive. Designs that conflict feel confusing.
+
+See `references/mental-models.md` for how to identify mental models and how they constrain design decisions.
+
+Create: `/docs/ux-research/mental-models/[persona-name]-[domain].md`
+
+### Step 3: Map User Journeys
+
+A journey map shows what a persona does, thinks, and feels across the full experience — before, during, and after interacting with the product. It reveals pain points the product must solve and moments where delight is possible.
+
+See `references/journey-mapping.md` for structure, touchpoints, and the file format.
+
+Create: `/docs/ux-research/journeys/[persona-name]-[goal].md`
+
+### Step 4: Update Value Proposition Canvas
+
+Research findings must flow back into the VPC. Personas reveal which customer jobs matter most. Journey maps reveal which pains are most painful and which gains are most valued.
+
+Update `/docs/value-proposition-canvas.md` with findings before handing off to story-mapping.
+
+## File Structure
+
+```
+docs/ux-research/
+├── personas/
+│   ├── [persona-name].md
+│   └── [persona-name].md
+├── mental-models/
+│   ├── [persona-name]-[domain].md
+│   └── [persona-name]-[domain].md
+└── journeys/
+    ├── [persona-name]-[goal].md
+    └── [persona-name]-[goal].md
+```
+
+## Integration
+
+```
+ux-research (this skill)  →  defines who, why, and how users think
+    ↓
+story-mapping             →  organizes work around user activities
+    ↓
+bdd-specification         →  writes scenarios
+```
+
+Personas are referenced by name in story map tasks and Gherkin scenarios. Journey maps inform which activities appear on the backbone and which tasks are Must Have vs Could Have.

package/ux-research/references/journey-mapping.md

@@ -0,0 +1,168 @@
+# Journey Mapping
+
+## What Is a Journey Map?
+
+A journey map traces a specific persona through a specific goal — from the moment they realize they need something to the moment they've accomplished it. It captures what they do, what they think, what they feel, and where things break down.
+
+Journey maps reveal two things no other method reveals:
+1. **Pain points** — the moments where frustration is highest. These are the problems the product must solve.
+2. **Delight opportunities** — the moments where a small improvement creates disproportionate satisfaction. These are where the product wins loyalty.
+
+## Scope
+
+One journey map per persona per goal. A goal is a single end-to-end accomplishment — not a feature, not a screen, but a thing the user wants to have done.
+
+**Good goal:** "Get paid for consulting work"
+**Bad goal (too broad):** "Run my business"
+**Bad goal (too narrow, this is a task not a goal):** "Click the Send button"
+
+## Journey Phases
+
+Every journey has these phases. Not every phase has the same number of steps — some journeys have a long "Become Aware" phase and a short "Act" phase. Map what actually happens, don't force equal length.
+
+### Phase 1: Become Aware
+The persona realizes they have a need or a problem. This often happens outside the product entirely.
+
+**Questions to answer:**
+- What triggers the realization? (deadline approaching, colleague mentions it, pain point hits)
+- What do they do first? (search online, ask someone, open a tool they already use)
+- What information are they looking for?
+
+### Phase 2: Decide
+The persona evaluates options — including doing nothing or continuing their current workaround.
+
+**Questions to answer:**
+- What alternatives do they consider?
+- What makes them choose one option over another?
+- What builds or destroys trust at this stage?
+
+### Phase 3: Act
+The persona does the thing. This is where the product is most directly involved.
+
+**Questions to answer:**
+- What steps do they take?
+- Where do they get stuck or confused?
+- What information do they need at each step that they don't have?
+- What do they expect to happen vs what actually happens?
+
+### Phase 4: Verify
+The persona checks that the thing worked. This is often overlooked in design but critical for trust.
+
+**Questions to answer:**
+- How does the persona know it worked?
+- What confirmation do they need?
+- What would make them doubt it worked?
+
+### Phase 5: Reflect
+The persona forms an opinion about the experience. This drives whether they come back, recommend the product, or look for alternatives.
+
+**Questions to answer:**
+- How do they feel about the experience overall?
+- What would they tell someone else about it?
+- What would make them do this again vs find another way?
+
+## Touchpoints
+
+A touchpoint is any point where the persona interacts with the product or with information related to the goal. Touchpoints include:
+
+- The product itself (screens, features)
+- Email communications (confirmations, reminders, receipts)
+- External systems (bank statements, email inbox, calendar)
+- Other people (colleagues, customers, accountants)
+- Physical artifacts (printed invoices, paper records)
+
+Map ALL touchpoints, not just the ones inside the product. The user's experience doesn't start when they open your app.
+
+## Emotion Curve
+
+At each step, note the persona's emotional state on a simple scale:
+
+```
+😤 Frustrated  →  😐 Neutral  →  😊 Satisfied  →  😄 Delighted
+```
+
+The emotion curve across the journey reveals the shape of the experience. A journey that starts frustrated and ends delighted is a success story. A journey that starts hopeful and ends frustrated is a churn risk.
+
+## File Format
+
+Create: `/docs/ux-research/journeys/[persona-name]-[goal].md`
+
+```markdown
+# Journey Map: [Persona Name] — [Goal]
+
+**Persona:** [Link to persona file]
+**Goal:** [The end-to-end accomplishment being mapped]
+**Current state:** Before product / With product (map both if product exists)
+
+## Journey Summary
+[2–3 sentences describing the overall shape of this journey and where the biggest pain points are]
+
+## Phase 1: Become Aware
+
+### Steps
+1. [What the persona does]
+2. [What the persona does]
+
+### Touchpoints
+- [Touchpoint 1]
+- [Touchpoint 2]
+
+### Thoughts
+- "[What the persona is thinking at this stage]"
+
+### Feelings
+😤 → 😐 (emotion at start → emotion at end of phase)
+
+### Pain Points
+- [What frustrates them here]
+
+### Opportunities
+- [What the product could do better here]
+
+---
+
+## Phase 2: Decide
+[Same structure as above]
+
+---
+
+## Phase 3: Act
+[Same structure — this is usually the longest phase]
+
+---
+
+## Phase 4: Verify
+[Same structure]
+
+---
+
+## Phase 5: Reflect
+[Same structure]
+
+---
+
+## Summary
+
+### Top Pain Points (ranked)
+1. [Biggest pain — most frustration, most friction]
+2. [Second biggest]
+3. [Third biggest]
+
+### Top Delight Opportunities (ranked)
+1. [Biggest opportunity — highest impact, most feasible]
+2. [Second biggest]
+3. [Third biggest]
+
+### Story Map Impact
+[How does this journey inform the story map?]
+- Activity [X] exists because of step [Y] in Phase [Z]
+- Task [A] is Must Have because Pain Point [B] is the primary reason users struggle
+- Task [C] is Could Have because it addresses a minor friction only
+```
+
+## Rules
+
+- Map the CURRENT state first (how the persona does it today, without or with the existing product). Then map the FUTURE state (how the product should change the journey). Comparing the two reveals exactly what the product must do.
+- Pain points in the current state become Must Have features. Delight opportunities become Should Have or Could Have.
+- Journey maps are living documents. Revisit when user research reveals new information or when the product changes significantly.
+- One journey map is not enough. Map at least the primary persona's most important goal. Ideally map each persona's primary goal.

package/ux-research/references/mental-models.md

@@ -0,0 +1,106 @@
+# Mental Models
+
+## What Is a Mental Model?
+
+A mental model is the internal framework a user has for understanding how something works. It is built from prior experience — other software they've used, physical analogies, and common sense. Users don't read documentation before forming mental models. They just start using the product and expect it to behave the way they already think about the problem.
+
+**When the product matches the mental model:** The user feels the product is intuitive. They find things where they expect them. Actions produce expected results.
+
+**When the product conflicts with the mental model:** The user feels confused. They look in the wrong place. They click the wrong button. They call it "unintuitive" — which actually means "it doesn't match how I already think about this."
+
+## Why Mental Models Matter
+
+Mental models are the single most important input to information architecture and interaction design. A product with beautiful visuals but wrong mental models will be abandoned. A product with simple visuals but correct mental models will feel effortless.
+
+## How to Identify Mental Models
+
+### Source 1: Existing Tools
+
+What does the persona currently use to do this job? The mental model is embedded in that tool's structure.
+
+**Example:** A business owner who currently invoices via a Word document thinks of invoices as documents — you create one, write on it, save it, print or email it. They do NOT think of invoices as database records with states and transitions.
+
+**Design implication:** The invoice creation flow should feel like composing a document, not filling out a database form. The "Save" action should feel like saving a document, not submitting a record.
+
+### Source 2: Physical Analogies
+
+What physical object or process does this domain map to in the user's mind?
+
+**Example:** Invoicing maps to "sending a bill" — a piece of paper you hand to someone expecting payment. Payment tracking maps to a "ledger" — a list of who owes what.
+
+**Design implication:** Use metaphors that match. An invoice list looks like a stack of papers or a ledger. A payment status looks like a checkmark next to an amount, not an abstract state machine.
+
+### Source 3: Common Software Patterns
+
+Users carry mental models from widely-used software. Email, file systems, shopping carts, and social feeds have trained billions of users in specific patterns.
+
+**Common mental models to leverage:**
+- **Inbox:** Messages arrive. You open them. You act on them or archive them.
+- **File system:** Things live in folders. You create, rename, move, delete.
+- **Shopping cart:** You browse, add things, review, checkout.
+- **Spreadsheet:** Data lives in rows and columns. You sort, filter, calculate.
+
+If your domain maps to one of these, lean into the metaphor. Don't fight it.
+
+## Mental Model Conflicts to Avoid
+
+### Conflict 1: Mixed Metaphors
+Using "inbox" metaphor for notifications but "file system" metaphor for the same data when accessed from a different screen. The user encounters the same thing in two incompatible mental frameworks.
+
+**Rule:** One mental model per domain concept. Pick it. Be consistent everywhere.
+
+### Conflict 2: System Mental Model ≠ User Mental Model
+Designing the UI around how the database is structured rather than how the user thinks about the problem.
+
+**Example (bad):** Invoice has states: DRAFT, PENDING_REVIEW, APPROVED, SENT, PAID, OVERDUE, CANCELLED. That's the system model. The user thinks: "I made an invoice. I sent it. They paid it." Three states, not seven.
+
+**Rule:** The UI exposes the user's mental model. The system model lives behind the scenes.
+
+### Conflict 3: Forcing a New Mental Model Without Justification
+Inventing a novel interaction pattern when a familiar one exists. Users have to unlearn before they can learn. This costs trust.
+
+**Rule:** Only introduce a new mental model when existing patterns genuinely cannot serve the need. And when you do, provide clear onboarding that explains the new way.
+
+## File Format
+
+Create: `/docs/ux-research/mental-models/[persona-name]-[domain].md`
+
+```markdown
+# Mental Model: [Persona Name] — [Domain]
+
+**Persona:** [Link to persona file]
+**Domain:** [What area of the product this covers — e.g., "invoicing", "payments"]
+
+## Current Mental Model
+[How does this persona currently think about this domain?
+Describe the metaphor or framework they use.]
+
+## Source
+[Where does this mental model come from?]
+- Existing tool: [tool name and how it shaped the model]
+- Physical analogy: [what real-world object/process maps to this]
+- Common software pattern: [inbox / file system / shopping cart / etc.]
+
+## Key Expectations
+[What does this mental model predict the product will do?]
+- [Expectation 1 — "I expect to find X in Y because that's where Z puts it"]
+- [Expectation 2]
+
+## Design Constraints
+[How does this mental model constrain UI decisions?]
+- [Constraint 1 — "Navigation must use [structure] because that matches how the user thinks about it"]
+- [Constraint 2]
+
+## Where the System Model Differs
+[Where does the technical reality conflict with the user's mental model?
+This is where translation is needed — the UI must hide the system model and present the user model.]
+- [Difference 1]
+- [Difference 2]
+```
+
+## Integration with Downstream Skills
+
+Mental models directly constrain:
+- **story-mapping:** The backbone activities should match the user's mental model of what they do, not the system's internal process names
+- **ux-design:** Information architecture must follow the mental model's structure
+- **bdd-specification:** Gherkin scenarios should use language that matches the mental model — "When I send the invoice" not "When I transition the invoice to SENT state"

package/ux-research/references/personas.md

@@ -0,0 +1,102 @@
+# Personas
+
+## What Is a Persona?
+
+A persona is a fictional but research-grounded character representing a distinct user segment. It is not a real person — it is a composite built from patterns in user data, business analysis, and domain knowledge. The persona becomes the subject of every design decision: "Would Sarah do this? Does this help Sarah?"
+
+## Deriving Personas from the Value Proposition Canvas
+
+The VPC already defines who the product serves. Personas make that concrete.
+
+### Step 1: Identify User Segments from Customer Jobs
+
+Read `/docs/value-proposition-canvas.md`. Each distinct type of person performing a customer job is a potential persona. Not every job needs its own persona — group jobs performed by the same type of person.
+
+**Example:**
+```
+Customer Jobs:
+- "Send invoices to customers quickly"        → performed by business owners
+- "Track who owes me money"                   → performed by business owners
+- "Generate financial reports for accountant" → performed by business owners
+- "Review and approve invoices"               → performed by accountants
+
+Personas:
+- Sarah, the business owner (covers jobs 1, 2, 3)
+- Marcus, the accountant (covers job 4)
+```
+
+### Step 2: Identify Pain Points Per Segment
+
+For each persona, pull the pains from the VPC that apply to their jobs. These become the persona's frustrations and motivations.
+
+### Step 3: Identify Goals Per Segment
+
+Pull the gains from the VPC. These become what the persona wants to achieve — the definition of success for them.
+
+## What Makes a Persona Useful
+
+A useful persona answers these questions:
+- What is this person trying to accomplish?
+- What do they currently do (before this product exists)?
+- What frustrates them about the current way?
+- What would make their life better?
+- How technically comfortable are they?
+- When and where do they do this work?
+
+A useless persona is just a name and a stock photo. If you can't answer the questions above, the persona is not grounded enough to make design decisions.
+
+## Rules
+
+- **2–4 personas per product.** More than 4 means the product is trying to serve too many different people. Focus.
+- **One primary persona.** The product is optimized for this person. Other personas are secondary — they benefit but are not the design target.
+- **Personas are not job titles.** "The small business owner" is a persona segment. "Sarah, who runs a 3-person consulting firm and does her own invoicing on her phone between client meetings" is a persona.
+- **Personas change.** Revisit when the product enters a new market or user research reveals a new segment.
+
+## File Format
+
+Create: `/docs/ux-research/personas/[persona-name].md`
+
+```markdown
+# Persona: [Name]
+
+**Segment:** [User segment this persona represents]
+**Primary:** Yes / No
+**Story map activities:** [Which backbone activities this persona performs]
+
+## Background
+[2–3 sentences. Who is this person in their daily life? What is their context?]
+
+## Goals
+[What does this persona want to accomplish with the product?]
+- [Goal 1 — pulled from VPC gains]
+- [Goal 2]
+
+## Frustrations
+[What currently gets in their way?]
+- [Frustration 1 — pulled from VPC pains]
+- [Frustration 2]
+
+## Current Behavior
+[What does this persona do RIGHT NOW to accomplish their goals, without this product?]
+- [Current workaround 1]
+- [Current workaround 2]
+
+## Technical Comfort
+- **Device:** [Primary device — phone, laptop, desktop]
+- **Comfort level:** Low / Medium / High
+- **Expectations:** [What does this persona expect software to do? e.g., "expects to find things quickly without reading instructions"]
+
+## Quotes
+[Representative statements this persona would make — in their voice, not the product's]
+- "[I spend 30 minutes every Friday manually typing invoices into a spreadsheet...]"
+- "[I always forget to follow up on unpaid invoices until it's too late...]"
+
+## Design Implications
+[How does this persona constrain or inform design decisions?]
+- [e.g., "Mobile-first — Sarah is usually between meetings when she needs to send an invoice"]
+- [e.g., "One-tap actions — Sarah has limited time and patience for multi-step flows"]
+```
+
+## Persona Priority Order
+
+When design decisions conflict between personas, the primary persona wins. Document the trade-off — don't silently ignore secondary personas. Sometimes a secondary persona's need can be accommodated without compromising the primary experience.