npx claudepluginhub geekatron/jerry --plugin jerryThis skill is limited to using the following tools:
<!-- VERSION: 1.5.0 | DATE: 2026-03-04 | SOURCE: skills/user-experience/SKILL.md | PARENT: /user-experience skill | REVISION: iter6 — fix inline citation at line 364 from Chapter 3 to Chapters 14-15 for behavior statement format, resolving contradiction with References table -->
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Version: 1.5.0 Framework: Jerry User-Experience -- Behavior Design Constitutional Compliance: Jerry Constitution v1.0 Parent Skill:
/user-experience(skills/user-experience/SKILL.md) Wave: 4 (Advanced Analytics) Project: PROJ-022 User Experience Skill | GitHub Issue #138
| Section | Purpose |
|---|---|
| Document Audience | Triple-Lens audience guide |
| Purpose | Sub-skill overview and key capabilities |
| When to Use This Sub-Skill | Activation triggers and scope boundaries |
| Available Agents | Single agent with role, model, and output location |
| P-003 Compliance | Worker agent hierarchy position |
| Invoking the Agent | Invocation via ux-orchestrator |
| Methodology | Fogg B=MAP framework, factor analysis, bottleneck identification, intervention design, 5-phase execution procedure |
| Output Specification | Output location, L0/L1/L2 structure, required sections |
| Routing | Keywords and lifecycle-stage routing integration |
| Cross-Framework Integration | Handoff from heuristic evaluation and to HEART metrics |
| Synthesis Hypothesis Confidence | Confidence classifications for Behavior Design outputs |
| Quality Gate Integration | S-014 scoring and H-13 threshold enforcement |
| Degraded Mode Behavior | Operation without real-time behavioral data |
| Wave Architecture | Wave 4 entry criteria, bypass conditions |
| Constitutional Compliance | Governing principles and AI-augmented analysis limitations |
| Registration | H-26 parent-routed registration model and AGENTS.md confirmation |
| Deployment Status | Wave 4 stub agent status and implementation timeline |
| Quick Reference | Common workflows and agent selection hints |
| References | Full repo-relative paths, requirements traceability, external citations |
This SKILL.md serves multiple audiences:
| Level | Audience | Sections to Focus On |
|---|---|---|
| L0 (Stakeholder) | Product managers, designers | Purpose, When to Use This Sub-Skill, Quick Reference |
| L1 (Developer) | Engineers invoking the agent | Invoking the Agent, Methodology, Output Specification |
| L2 (Architect) | Workflow designers, skill maintainers | Cross-Framework Integration, Synthesis Hypothesis Confidence, Degraded Mode Behavior |
The Behavior Design sub-skill provides structured behavioral bottleneck diagnosis using BJ Fogg's Behavior Model, commonly expressed as B=MAP: Behavior happens when Motivation, Ability, and a Prompt converge at the same moment (Fogg, 2009; Fogg, 2020). It targets tiny teams (1-5 people) who observe users failing to complete desired actions and need a systematic framework to identify which behavioral factor is the limiting constraint.
This sub-skill is part of Wave 4 (Advanced Analytics), requiring Wave 3 completion before deployment. It bridges design system construction (Wave 3) and process-intensive activities (Wave 5) by providing behavioral insight that explains why well-designed interfaces still fail to drive target user actions.
Activate when:
Do NOT use for:
/ux-heuristic-eval (Nielsen's 10) instead. Use heuristic evaluation first, then Behavior Design to trace severe issues to behavioral root causes./ux-atomic-design (Atomic Design) instead./ux-inclusive-design (WCAG 2.2) instead./ux-heart-metrics (Google GSM) instead. Use Behavior Design first to diagnose, then HEART to measure improvement./ux-jtbd (Jobs-to-Be-Done) instead. JTBD identifies what users want; Behavior Design diagnoses why they fail to complete a specific action./ux-lean-ux (Lean UX) instead./ux-design-sprint (Design Sprint 2.0) instead./ux-kano-model (Kano) instead./eng-team instead./problem-solving instead.| Agent | Role | Tier | Mode | Model | Output Location |
|---|---|---|---|---|---|
ux-behavior-diagnostician | Fogg B=MAP behavior bottleneck diagnostician | T2 | Convergent | Sonnet | projects/${JERRY_PROJECT}/engagements/{engagement-id}/ux-behavior-diagnostician-{topic-slug}.md |
STUB: The agent definition file (skills/ux-behavior-design/agents/ux-behavior-diagnostician.md) is pending Wave 4 Phase 2 implementation as part of PROJ-022 EPIC-004. The SKILL.md specifies the methodology and output contract that the agent will implement.
Tool tier: T2 (Read-Write) = Read, Write, Edit, Glob, Grep, Bash. No WebSearch, WebFetch, or Context7 MCP access -- the B=MAP methodology is self-contained. See .context/rules/agent-development-standards.md [Tool Security Tiers].
The agent produces output at three levels per AD-M-004:
The /ux-behavior-design sub-skill contains a single worker agent. It is invoked by the ux-orchestrator (T5) via the Agent tool. The agent does NOT have Agent tool access and MUST NOT spawn sub-agents.
MAIN CONTEXT (user request)
|
v
ux-orchestrator (T5, Opus, Integrative) -- parent orchestrator
|
+-- ux-behavior-diagnostician (T2, Convergent, Sonnet) -- THIS sub-skill's worker
+-- [other sub-skill workers...]
Enforcement:
disallowedTools: [Agent] declared in skills/ux-behavior-design/agents/ux-behavior-diagnostician.md frontmatterskills/ux-behavior-design/agents/ux-behavior-diagnostician.governance.yaml capabilities.forbidden_actionsskills/user-experience/rules/ci-checks.md)This is a sub-skill invoked by the ux-orchestrator, not directly by users. Users interact with the parent /user-experience skill, which routes to this sub-skill based on lifecycle-stage triage.
"Why aren't users completing the checkout process?"
"Diagnose the behavioral bottleneck in our onboarding flow"
"Users see the CTA but don't click it -- what's blocking them?"
"Analyze motivation, ability, and prompts for the signup action"
"Why are users abandoning the form after filling out 3 of 5 fields?"
"What's preventing users from upgrading to the paid plan?"
"Use ux-behavior-diagnostician to diagnose why users abandon the payment form"
"Have ux-behavior-diagnostician analyze B=MAP factors for the onboarding tutorial"
The ux-orchestrator invokes the agent via the Agent tool:
Agent(
description="ux-behavior-diagnostician: B=MAP bottleneck diagnosis for checkout abandonment",
subagent_type="jerry:ux-behavior-diagnostician",
prompt="""
## UX CONTEXT (REQUIRED)
- **Engagement ID:** UX-0001
- **Topic:** Checkout Abandonment Bottleneck Diagnosis
- **Product:** [product name and domain]
- **Target Users:** [user description]
- **Target Behavior:** [specific action users should take but are not taking]
- **Current Behavior Data:** [what users are doing instead, abandonment rates, funnel data]
- **Input:** [screenshots, flow descriptions, upstream heuristic findings]
## TASK
Diagnose the behavioral bottleneck preventing users from completing checkout.
1. Define the target behavior in specific, observable terms
2. Assess Motivation factors (intrinsic, extrinsic, social drivers)
3. Assess Ability factors (6 Fogg simplicity factors)
4. Assess Prompt factors (type, timing, placement)
5. Identify the primary bottleneck via elimination algorithm
6. Recommend targeted interventions for the diagnosed bottleneck
## MANDATORY PERSISTENCE (P-002)
Create file at: projects/${JERRY_PROJECT}/engagements/UX-0001/ux-behavior-diagnostician-checkout-abandonment.md
"""
)
Governance codification (AD-M-007): The session_context contract (on_receive/on_send) is specified in
ux-behavior-diagnostician.governance.yamlper AD-M-007. Fields are enumerated below:
on_receive fields:
| Field | Type | Required | Description |
|---|---|---|---|
engagement_id | string | Yes | UX engagement identifier (format: UX-{NNNN}) |
product_context | string | Yes | Product name, domain, and target user description |
target_behavior | string | Yes | Specific, observable action users should take but are not taking (e.g., "click 'Complete Purchase' button on checkout page") |
current_behavior_data | string | No | Observed user behavior: abandonment rates, funnel stage, click data, session recordings summary |
upstream_artifacts | array | No | File paths to upstream handoff artifacts (heuristic evaluation severity-rated findings, screenshots, flow descriptions) |
on_send fields:
| Field | Type | Required | Description |
|---|---|---|---|
bottleneck_factor | enum | Yes | Primary bottleneck: motivation, ability, prompt, or multiple |
bottleneck_severity | enum | Yes | critical (never occurs), major (rare), moderate (inconsistent) |
motivation_assessment | object | Yes | Intrinsic/extrinsic/social scores (1-5 each), overall above/below threshold |
ability_assessment | object | Yes | Six simplicity factor scores (1-5 each), overall above/below threshold |
prompt_assessment | object | Yes | Type (facilitator/signal/spark), timing, placement |
interventions | array | Yes | Interventions with effort estimate and expected impact |
synthesis_judgments | array | Yes | AI judgment calls with confidence classification and rationale |
The Fogg Behavior Model (Fogg, 2009, DOI: 10.1145/1541948.1541999; Fogg, 2020) states that B=MAP: behavior occurs when Motivation, Ability, and Prompt converge above their respective thresholds at the same moment. If any factor is missing or below the action threshold, the behavior does not occur -- all three factors must be simultaneously sufficient.
The model uses a motivation (Y-axis) vs. ability (X-axis) plane with a curved action line. A user with high motivation but high friction falls below the line; a user who finds the action easy but lacks motivation also falls below. The prompt must arrive when the user is above the action line (Fogg, 2009).
Motivation in the Fogg model operates through three core motivator pairs (Fogg, 2009):
| Motivator Pair | High End | Low End | Assessment Question |
|---|---|---|---|
| Sensation | Pleasure | Pain | Does the action produce immediate pleasure or relieve pain? |
| Anticipation | Hope | Fear | Does the user hope for reward or fear consequence? |
| Belonging | Acceptance | Rejection | Does the action increase social standing or prevent exclusion? |
Intrinsic motivators: Internal drives (satisfaction, curiosity, mastery, autonomy). Durable but difficult to create through design alone (Fogg, 2020).
Extrinsic motivators: External incentives (rewards, punishments, progress indicators). Easier to design but less durable; decay when the incentive is removed (Fogg, 2020).
Social drivers: Peer influence (competition, collaboration, recognition, social proof). Operate through the belonging motivator pair (Fogg, 2009).
Motivation assessment scale: Each motivation dimension (intrinsic, extrinsic, social) is rated 1-5 based on available evidence:
Ability in the Fogg model is inversely related to simplicity. The six simplicity factors (Fogg, 2009) represent distinct dimensions of friction that can prevent a user from completing the target behavior:
| Factor | Definition | Assessment Question | Example Friction |
|---|---|---|---|
| Time | How long the behavior takes to complete | Does the action take more time than the user is willing to spend? | 12-field form when user expects 3 fields |
| Money | Financial cost of the behavior | Does the action require spending more money than the user expected? | Surprise shipping costs at checkout |
| Physical Effort | Bodily exertion required | Does the action require more physical effort than the user is willing to expend? | Requiring camera access, photo upload, manual data entry on mobile |
| Brain Cycles | Cognitive load required | Does the action require more thinking than the user is willing to invest? | Complex pricing tiers requiring comparison; unfamiliar terminology |
| Social Deviance | Degree to which the behavior violates social norms | Does the action require the user to do something socially unacceptable in their context? | Publicly sharing salary information; requesting social media permissions |
| Non-Routine | Degree to which the behavior departs from the user's established habits | Does the action require the user to change an existing habit or adopt a new workflow? | Switching from email-based workflow to an unfamiliar dashboard |
Simplicity factor assessment scale: Each factor is rated 1-5:
The limiting simplicity factor is the factor with the lowest score. Per Fogg (2009), ability is governed by the scarcest resource at the moment of the prompt -- improving any factor except the limiting one does not raise overall ability above the action threshold.
Prompts are the triggers that call users to action. The Fogg model identifies three prompt types, each appropriate for a specific motivation-ability state (Fogg, 2009):
| Prompt Type | User State | Mechanism | Design Implication |
|---|---|---|---|
| Spark | High ability, low motivation | The prompt simultaneously triggers motivation (e.g., emotional appeal, social proof, fear of missing out) | User can do the action but needs a reason; the prompt provides that reason |
| Facilitator | High motivation, low ability | The prompt simultaneously reduces friction (e.g., pre-filled forms, one-click actions, simplified steps) | User wants to act but the action is too hard; the prompt makes it easier |
| Signal | High motivation, high ability | The prompt serves as a simple reminder or notification (e.g., bell icon, push notification, calendar reminder) | User is both willing and able; they just need a timely nudge |
Prompt assessment dimensions:
| Dimension | Assessment | Values |
|---|---|---|
| Type match | Is the prompt type appropriate for the user's motivation-ability state? | Appropriate (correct type for state), Mismatched (wrong type -- e.g., signal prompt when facilitator is needed) |
| Timing | Does the prompt arrive when the user is ready to act? | Appropriate (arrives at the right moment), Mistimed (arrives too early or too late), Absent (no prompt exists) |
| Placement | Is the prompt visible and actionable when it fires? | Visible (user notices it), Hidden (below fold, in a submenu), Competing (surrounded by other CTAs that dilute attention) |
The diagnostician follows a structured elimination algorithm to identify the primary bottleneck:
Step 1: Prompt Assessment (cheapest fix first)
Step 2: Ability Assessment (most common bottleneck)
Step 3: Motivation Assessment (hardest to change)
Step 4: Multiple Bottleneck Assessment
multiple bottleneck requiring coordinated interventions.Algorithm ordering rationale: The prompt-first, ability-second, motivation-third ordering follows Fogg's (2020) intervention difficulty gradient: prompts are cheapest to fix, ability is moderate, motivation is hardest.
Based on the diagnosed bottleneck, the diagnostician recommends interventions targeted at the weakest factor:
| Bottleneck | Intervention Category | Example Interventions | Effort |
|---|---|---|---|
| Prompt | Add, reposition, or retype the prompt | Add CTA where none exists; move above fold; change signal to spark for low-motivation users | Low |
| Ability (Time) | Reduce time required | Pre-fill fields; reduce steps; add progress indicators; offer express path | Low-Medium |
| Ability (Money) | Reduce or clarify cost | Show total upfront; offer free tier; defer payment | Medium |
| Ability (Physical Effort) | Reduce physical actions | Add autofill; one-click actions; optimize for mobile | Low-Medium |
| Ability (Brain Cycles) | Reduce cognitive load | Simplify language; add defaults; reduce choices; add tooltips | Medium |
| Ability (Social Deviance) | Normalize the behavior | Add social proof; anonymization options; privacy controls | Medium |
| Ability (Non-Routine) | Reduce habit disruption | Map to existing workflows; familiar UI patterns; transition guides | Medium-High |
| Motivation | Increase motivation via design | Social proof; gamification; loss aversion framing; progress visualization | High |
| Multiple | Coordinated multi-factor | Address lowest-scoring factor first; combine prompt redesign with simplification | High |
Note: This execution procedure describes target behavior for the fully-implemented
ux-behavior-diagnosticianagent. The current agent definition is a Wave 4 stub; full implementation will follow this specification.
The diagnostician follows a 5-phase sequential workflow. Each phase produces intermediate artifacts that feed the next. This mirrors the Phase 1-5 structure established by the HEART metrics, Lean UX, and Atomic Design sub-skills.
Purpose: Establish the behavioral context, define the target behavior, confirm wave entry criteria, and catalog available behavioral evidence.
Activities:
WAVE-3-SIGNOFF.md in projects/${JERRY_PROJECT}/engagements/; if absent, ask user per H-31.)/ux-heuristic-eval severity-rated findings (severity >= 2); if present, import finding IDs for bottleneck contextOutput: Scope brief with the following required fields:
| Field | Description | Example |
|---|---|---|
| Product Domain | Application area and target user segment | "E-commerce checkout flow for first-time buyers" |
| Target Behavior Statement | Fogg format: "After [CONTEXT], I will [SPECIFIC BEHAVIOR]" | "After adding items to cart, I will complete purchase" |
| Observation Scope | Screens, flows, or interaction sequences under analysis | "Cart page through order confirmation (4 screens)" |
| Upstream Findings | Imported heuristic evaluation findings (if available), with finding IDs | "HE-003 (severity 3): unclear CTA placement" |
| Evidence Inventory | Available behavioral evidence classified as strong/moderate/weak | "Strong: 23% cart abandonment rate; Moderate: 3 user interviews; Weak: support ticket anecdotes" |
| Wave Entry Status | Wave 4 criteria verification result | "PASS: WAVE-3-SIGNOFF.md present, 7 Atom stories confirmed" |
Purpose: Map the current state of each B=MAP factor, establishing a baseline assessment.
Activities:
Output: B=MAP state map: motivation scores, ability scores with limiting factor, prompt assessment, action-line position.
Purpose: Apply the bottleneck identification algorithm to determine the primary constraint.
Activities:
Output: Bottleneck diagnosis: primary factor, severity, evidence chain, algorithm trace, confidence assessment.
Purpose: Recommend targeted interventions addressing the diagnosed bottleneck.
Activities:
Output: Prioritized interventions: description, target factor, impact, effort, direct/supporting, confidence (all LOW).
Purpose: Synthesize findings, produce L0/L1/L2 output artifact, construct downstream handoff.
Activities:
/ux-heart-metrics handoff: bottleneck diagnosis with HEART dimension mapping for measurement baselineOutput: Complete output artifact per the Required Output Sections specification (L0 executive summary, L1 technical sections, L2 strategic implications, synthesis judgments, handoff data). Handoff payload for /ux-heart-metrics.
projects/${JERRY_PROJECT}/engagements/{engagement-id}/ux-behavior-diagnostician-{topic-slug}.md
Where:
{engagement-id} follows the pattern UX-{NNNN} (e.g., UX-0001){topic-slug} is a kebab-case descriptor of the target behavior (e.g., checkout-abandonment, onboarding-completion, plan-upgrade)| Section | Level | Content |
|---|---|---|
| Executive Summary | L0 | Primary bottleneck factor; bottleneck severity; top intervention recommendation; key findings for stakeholders and cross-framework synthesis input |
| Engagement Context | L1 | Product description, target users, target behavior statement, available evidence inventory, observation scope, upstream inputs, wave entry verification |
| Behavior State Map | L1 | Full B=MAP assessment: motivation scores (intrinsic, extrinsic, social; 1-5 each), ability scores (6 simplicity factors; 1-5 each with limiting factor identified), prompt assessment (type, timing, placement), action-line position |
| Bottleneck Diagnosis | L1 | Primary bottleneck factor with elimination algorithm trace; bottleneck severity; evidence chain; confidence assessment |
| Intervention Recommendations | L1 | Prioritized interventions (3-5) with: description, target factor, expected impact, implementation effort, direct/supporting classification; all marked LOW confidence |
| Strategic Implications | L2 | Behavioral pattern analysis; systemic bottleneck trends; behavior design maturity assessment; behavior change roadmap |
| Synthesis Judgments Summary | L1 | Each AI judgment call listed for synthesis confidence gate compliance |
| Handoff Data | L1 | Structured data for downstream sub-skills: bottleneck diagnosis with HEART metric mapping (for /ux-heart-metrics measurement baseline) |
Synthesis Judgments Summary requirements: MUST list every AI judgment (motivation ratings, simplicity scores, bottleneck classification, interventions) with confidence classification (HIGH/MEDIUM/LOW) and rationale. Each judgment row includes: finding ID, framework source (e.g., B=MAP factor, simplicity factor, intervention category), confidence level (HIGH/MEDIUM/LOW), and rationale explaining the classification basis and evidence chain. Follows the pattern in skills/user-experience/rules/synthesis-validation.md [STUB: EPIC-001].
| Template | Path | Purpose |
|---|---|---|
| B=MAP Diagnosis Template | skills/ux-behavior-design/templates/bmap-diagnosis-template.md | B=MAP factor assessment with scoring tables, bottleneck algorithm trace, and intervention recommendation format |
| Keyword | Routing Context |
|---|---|
| behavior design | Direct match -- primary trigger |
| B=MAP | Direct match |
| Fogg model | Direct match |
| behavior bottleneck | Direct match |
| motivation analysis | In combination with UX/behavior context |
| ability analysis | In combination with UX/behavior context |
| prompt design | In combination with behavior/UX context (not general prompt engineering) |
| why users don't | Direct match (phrase) |
| user inaction | Direct match |
| behavior diagnosis | Direct match |
| tiny habits | In combination with UX/design context |
| action threshold | In combination with behavior/UX context |
This sub-skill is routed to by the ux-orchestrator in the following lifecycle-stage scenarios:
| Stage | User Intent | Route Condition |
|---|---|---|
| After launch | "Users not completing action" | Direct route to /ux-behavior-design; source: skills/user-experience/rules/ux-routing-rules.md Stage Routing Table (pending EPIC-001 completion) |
| After launch | Follow-up from heuristic evaluation | When /ux-heuristic-eval has identified severity >= 2 findings with behavioral implications; heuristic findings provide context for bottleneck diagnosis |
| CRISIS | Urgent UX problems (step 2) | CRISIS mode invokes Behavior Design as step 2 of the fixed 3-skill emergency sequence (Heuristic Eval -> Behavior Design -> HEART Metrics); source: skills/user-experience/rules/ux-routing-rules.md CRISIS Routing (pending EPIC-001 completion) |
| Any stage | "Fix a specific UX problem" (behavioral) | Qualification question: "Is the problem about user behavior or design quality?" -> Behavior: /ux-behavior-design; source: skills/user-experience/rules/ux-routing-rules.md Common Intent Resolution (pending EPIC-001 completion) |
This sub-skill is in Wave 4 (Advanced Analytics). It requires Wave 3 completion before deployment:
Entry criteria: Wave 3: Storybook with 5+ Atom stories AND 1 Persona Spectrum review.
Bypass condition: Existing user base with analytics (skip Persona Spectrum prerequisite). This bypass recognizes that teams with an existing user base and analytics data have the behavioral evidence needed for B=MAP diagnosis, even without the Persona Spectrum review that Wave 3 inclusive design would normally provide.
This sub-skill receives context from other sub-skills when invoked as part of a multi-sub-skill workflow:
| From Sub-Skill | Handoff Artifact | Key Fields | Usage |
|---|---|---|---|
/ux-heuristic-eval | Severity-rated findings | Finding ID, heuristic violated, severity (0-4), affected screen/flow | Heuristic findings with severity >= 2 provide context for behavioral diagnosis; high-severity findings identify specific UI locations where user behavior breaks down, guiding the B=MAP scope definition |
This sub-skill produces artifacts that feed into other sub-skills via the Jerry handoff protocol (docs/schemas/handoff-v2.schema.json).
| To Sub-Skill | Handoff Artifact | Key Fields | Trigger |
|---|---|---|---|
/ux-heart-metrics | Bottleneck diagnosis with HEART metric mapping | Bottleneck factor, bottleneck severity, affected screen/flow, candidate HEART metric category (Happiness/Engagement/Adoption/Retention/Task Success), intervention list | After bottleneck diagnosis is complete; HEART analyst establishes measurement baselines for the diagnosed bottleneck area |
Handoff data format (handoff-v2 + ux-ext):
handoff:
from_agent: ux-behavior-diagnostician
to_agent: ux-heart-analyst
task: "Establish HEART metric baselines for diagnosed behavioral bottleneck"
success_criteria:
- "Metric baselines established for affected HEART dimension"
- "Target thresholds set for post-intervention measurement"
artifacts:
- "projects/${JERRY_PROJECT}/engagements/{engagement-id}/ux-behavior-diagnostician-{topic-slug}.md"
key_findings:
- "Primary bottleneck: {factor} ({severity})"
- "Limiting simplicity factor: {factor_name} (score: {N}/5)"
blockers: []
confidence: 0.6
criticality: C2
ux_ext:
bottleneck_factor: "{motivation|ability|prompt|multiple}"
bottleneck_severity: "{critical|major|moderate}"
affected_heart_dimension: "{happiness|engagement|adoption|retention|task_success}"
This sub-skill participates in the following canonical sequences:
| Sequence | Skills Involved | This Sub-Skill's Role |
|---|---|---|
| Evaluate to Diagnose to Measure | /ux-heuristic-eval then /ux-behavior-design then /ux-heart-metrics | Receives heuristic findings and traces them to behavioral root causes via B=MAP; hands off bottleneck diagnosis to HEART for measurement |
| CRISIS Emergency Sequence | /ux-heuristic-eval then /ux-behavior-design then /ux-heart-metrics | Step 2 of the fixed CRISIS 3-skill sequence; diagnoses behavioral root causes of urgent UX problems |
Behavior Design outputs include synthesis hypotheses that carry confidence classifications per the synthesis validation protocol.
| Synthesis Step | Typical Confidence | Rationale |
|---|---|---|
| B=MAP bottleneck diagnosis | MEDIUM | Fogg Behavior Model (Fogg, 2020) provides structured diagnosis but bottleneck attribution requires user-specific data. Framework constrains to three factors, reducing interpretive variance, but scores depend on evidence quality. |
| Design intervention recommendation | LOW | Intervention effectiveness depends on context-specific factors (demographics, domain, constraints) that training data cannot capture. Directionally sound per B=MAP but requires user testing (Fogg, 2020). |
Gate enforcement:
[REFERENCE-ONLY]. Banner: "Intervention recommendations are directional based on B=MAP analysis. Effectiveness requires validation through user testing or A/B experimentation."Note on confidence dynamics: Bottleneck diagnosis can achieve HIGH synthesis confidence when converged with a second framework -- for example, when /ux-heuristic-eval identifies severity >= 3 findings corroborating the diagnosed bottleneck. Intervention recommendations remain LOW regardless of diagnostic confidence because effectiveness requires empirical testing.
Behavior Design outputs are subject to the Jerry quality gate per H-13 and H-14:
| Quality Check | Threshold | Application |
|---|---|---|
| S-014 LLM-as-Judge scoring | >= 0.92 composite (C2+) | Applied at Phase 5 completion |
| Creator-critic-revision | Minimum 3 iterations (H-14) | Orchestrator manages revision cycles |
| Self-review (S-010) | Required before presenting | Self-review before returning to orchestrator |
| Wave transition gate | S-014 composite >= 0.85 | Applied at Wave 4 -> 5 transition |
Scoring dimensions (Behavior Design interpretation):
| Dimension | Weight | Interpretation |
|---|---|---|
| Completeness | 0.20 | All B=MAP factors assessed; all six simplicity factors rated; prompt analysis included |
| Internal Consistency | 0.20 | Bottleneck diagnosis consistent with factor scores; interventions target diagnosed bottleneck |
| Methodological Rigor | 0.20 | Fogg model correctly applied; elimination algorithm followed; factor ratings evidence-based |
| Evidence Quality | 0.15 | Factor ratings cite evidence; evidence quality classified; inferences labeled |
| Actionability | 0.15 | Interventions specific, implementable, prioritized by effort-to-impact |
| Traceability | 0.10 | Findings trace to evidence; synthesis judgments documented; upstream findings cited |
The following CI gate criteria apply to this sub-skill (full gate definitions in skills/user-experience/rules/ci-checks.md):
| Gate | Check | Enforcement |
|---|---|---|
| No Agent tool access | disallowedTools: [Agent] present in agent frontmatter; agent MUST NOT have Agent in tools list | L5 (CI): grep agent frontmatter for Agent tool presence |
| P-003 forbidden action | capabilities.forbidden_actions in .governance.yaml MUST include P-003 recursive subagent prohibition | L5 (CI): schema validation of governance YAML against docs/schemas/agent-governance-v1.schema.json |
| Output schema validation | Agent output MUST contain all Required Output Sections (Executive Summary, Engagement Context, Behavior State Map, Bottleneck Diagnosis, Intervention Recommendations, Strategic Implications, Synthesis Judgments Summary, Handoff Data) | L4 (post-tool): section heading presence check on output artifact |
The ux-behavior-diagnostician operates at T2 (Read-Write) and does NOT have access to WebSearch, WebFetch, or Context7 MCP tools. Additionally, it operates on user-provided descriptions and artifacts rather than live behavioral analytics. The following degraded modes apply:
When the user cannot provide quantitative behavioral data (analytics, funnel metrics, session recordings):
| Limitation | Impact | Mitigation |
|---|---|---|
| No conversion rate data | Cannot quantify bottleneck severity precisely | Ask for qualitative assessment: "How often does this fail?" Map: "never" = critical, "rarely" = major, "sometimes" = moderate |
| No funnel analytics | Cannot identify exact drop-off point | Ask user to describe the last step before abandonment |
| No session recordings | Cannot observe actual behavior patterns | Ask: (1) "What do users do instead of the target action?" (2) "At what step do users stop? Describe the last thing they do before abandoning." (3) "Have you observed any user confusion or frustration signals (support tickets, rage clicks, dead-end navigation)?" |
| No A/B test data | Cannot validate interventions empirically | Mark all interventions LOW confidence; recommend user testing |
Degraded mode disclosure (P-022):
[DEGRADED MODE] This output was produced without real-time behavioral analytics data.
Factor assessments are based on user-provided descriptions and available interface artifacts.
Limitations:
- Bottleneck severity estimated from qualitative descriptions, not quantitative data
- Ability factor scores may not reflect actual user friction without session recordings
- Intervention recommendations are directional and require empirical validation
When invoked without prior /ux-heuristic-eval output (e.g., direct invocation rather than CRISIS sequence), the diagnostician performs its own high-level interface assessment based on provided screenshots or descriptions. This is less rigorous than a formal heuristic evaluation. Bottleneck diagnosis references screen locations and behaviors rather than heuristic finding IDs.
When the user provides only text descriptions without visual references, the diagnostician asks structured questions to compensate: prompt visibility and placement ("Where does the CTA appear? What else is visible around it?") and flow structure ("Describe the step sequence from entry to target action").
This sub-skill is part of Wave 4 (Advanced Analytics), alongside /ux-kano-model.
Entry criteria: Wave 3 completed -- Storybook with 5+ Atom stories AND 1 Persona Spectrum review.
Bypass condition: Existing user base with analytics (skip Persona Spectrum prerequisite). Bypass requires 3-field documentation: unmet criterion, impact assessment ("behavior diagnosis proceeds without inclusive design context"), and remediation plan with target date.
Wave transition to Wave 5: Requires 30+ users for Kano survey OR 1 B=MAP bottleneck diagnosed.
All agents in this sub-skill adhere to the Jerry Constitution v1.0:
| Principle | Requirement | Consequence of Violation |
|---|---|---|
| P-003 | NEVER spawn recursive subagents -- worker agent, no Agent tool access | Agent hierarchy violation; uncontrolled token consumption |
| P-020 | NEVER override user decisions on bottleneck classification or intervention priorities | Unauthorized action; trust erosion |
| P-022 | NEVER present bottleneck diagnoses as certain without disclosing evidence limitations; NEVER inflate factor scores without supporting evidence; NEVER omit the degraded mode disclosure when operating without behavioral data | Governance undermined; quality assessment invalidated |
| P-001 | NEVER present factor ratings or bottleneck classifications without citing the evidence or reasoning supporting the assessment | Unreliable outputs; unfounded claims propagate downstream |
| P-002 | NEVER leave bottleneck diagnoses or intervention recommendations in transient context only -- persist to files | Context rot vulnerability; artifacts lost on session compaction |
Per-agent enforcement: The ux-behavior-diagnostician agent declares:
constitution.principles_applied: P-003, P-020, P-022, P-001, P-002 in skills/ux-behavior-design/agents/ux-behavior-diagnostician.governance.yamlcapabilities.forbidden_actions: 3 entries in NPT-009 format referencing the constitutional tripletdisallowedTools: [Agent] in skills/ux-behavior-design/agents/ux-behavior-diagnostician.md frontmatterThe Behavior Design diagnostician agent operates as an AI-augmented analysis tool. The following limitations apply to all outputs and MUST be disclosed per P-022 (no deception):
This sub-skill follows a parent-routed registration model per H-26. Sub-skills are routed through the parent /user-experience orchestrator; independent registration would create duplicate triggers (AP-02).
| Registration Point | Status | Detail |
|---|---|---|
CLAUDE.md skill table | Registered via parent | /user-experience registered; sub-skills not independently listed |
mandatory-skill-usage.md trigger map | Routed via parent | "behavior design" keyword routes to parent, which dispatches here |
AGENTS.md agent registry | Registered | ux-behavior-diagnostician listed under User-Experience Skill Agents |
| Parent SKILL.md agent table | Registered | Listed in skills/user-experience/SKILL.md [Available Agents] |
Wave 4 Sub-Skill -- Phase 1 Complete, Phase 2 Pending.
This sub-skill follows a two-phase implementation sequence:
- Wave 4 Phase 1 (this deliverable): SKILL.md specification -- methodology, output format, routing integration, template stub, cross-framework integration, and quality gate criteria. This document is the Phase 1 artifact.
- Wave 4 Phase 2 (pending): Agent implementation --
skills/ux-behavior-design/agents/ux-behavior-diagnostician.md(agent definition with<input>,<capabilities>,<methodology>,<output>sections) andskills/ux-behavior-design/agents/ux-behavior-diagnostician.governance.yaml(governance metadata). Tracked under PROJ-022 EPIC-004.
| Need | Command Example |
|---|---|
| Diagnose checkout abandonment | "Why aren't users completing the checkout process?" |
| Analyze onboarding drop-off | "Diagnose the behavioral bottleneck in our onboarding flow" |
| Understand CTA inaction | "Users see the upgrade button but don't click it -- what's blocking them?" |
| B=MAP factor analysis | "Analyze motivation, ability, and prompts for the signup action" |
| Post-launch behavior diagnosis | "Users are abandoning the form after step 3 -- diagnose why" |
| CRISIS behavioral diagnosis | "CRISIS: users are abandoning checkout -- urgent UX triage" (routes to full CRISIS sequence) |
| Keywords | Routes To |
|---|---|
| behavior design, B=MAP, Fogg model, behavior bottleneck, motivation analysis, ability analysis, prompt design, user inaction, action threshold, tiny habits | ux-behavior-diagnostician |
| heuristic, usability, Nielsen, severity, inspection, evaluation | /ux-heuristic-eval (not this sub-skill) |
| HEART, metrics, measurement, GSM, happiness, engagement | /ux-heart-metrics (not this sub-skill) |
| lean UX, hypothesis, assumption, experiment, build-measure-learn | /ux-lean-ux (not this sub-skill) |
| jobs to be done, JTBD, switch interview, user motivation | /ux-jtbd (not this sub-skill) |
| Kano, feature prioritization, must-be, attractive, performance | /ux-kano-model (not this sub-skill) |
| Source | Content | Path |
|---|---|---|
| Parent SKILL.md | Sub-skill scope, wave architecture, routing, MCP dependencies, synthesis protocol | skills/user-experience/SKILL.md |
| Agent definition | Agent frontmatter, identity, expertise, guardrails | skills/ux-behavior-design/agents/ux-behavior-diagnostician.md [PLANNED] |
| Agent governance | Tool tier, forbidden actions, output validation, constitutional compliance | skills/ux-behavior-design/agents/ux-behavior-diagnostician.governance.yaml [PLANNED] |
| UX routing rules | Lifecycle-stage routing, handoff data contracts, common intent resolution, CRISIS routing [PARTIAL: EPIC-001] | skills/user-experience/rules/ux-routing-rules.md |
| Synthesis validation | Confidence gate protocol, per-sub-skill confidence map, signal extraction criteria | skills/user-experience/rules/synthesis-validation.md [STUB: EPIC-001] |
| Wave progression | Wave 4 entry criteria, signoff requirements | skills/user-experience/rules/wave-progression.md |
| CI checks | P-003 enforcement, sub-skill validation gates | skills/user-experience/rules/ci-checks.md |
| B=MAP diagnosis template | Factor assessment tables, bottleneck algorithm trace, intervention format | skills/ux-behavior-design/templates/bmap-diagnosis-template.md |
| Skill standards | H-25/H-26 skill structure requirements | .context/rules/skill-standards.md |
| Agent development standards | H-34 dual-file architecture, tool tiers, handoff protocol | .context/rules/agent-development-standards.md |
| Quality enforcement | Quality gate thresholds, criticality levels, strategy catalog | .context/rules/quality-enforcement.md |
| Handoff schema | Canonical handoff schema v2 | docs/schemas/handoff-v2.schema.json |
| Agent governance schema | Governance YAML validation schema | docs/schemas/agent-governance-v1.schema.json |
| Source | Content | Path |
|---|---|---|
| PROJ-022 PLAN.md | Project plan: sub-skill scope, wave assignment, acceptance criteria, implementation phases | projects/PROJ-022-user-experience-skill/PLAN.md |
| EPIC-004 (Wave 4 Deployment) | Parent work item for Wave 4 sub-skill implementation including this sub-skill | PROJ-022 EPIC-004 in projects/PROJ-022-user-experience-skill/WORKTRACKER.md |
| ORCHESTRATION.yaml | Orchestration plan governing the build sequence for this sub-skill | projects/PROJ-022-user-experience-skill/orchestration/ux-skill-build-20260303-001/ORCHESTRATION.yaml |
| Source | Citation |
|---|---|
| Fogg, B.J. (2009) | "A Behavior Model for Persuasive Design." Proceedings of the 4th International Conference on Persuasive Technology (Persuasive '09). Article No. 40. DOI: 10.1145/1541948.1541999. Original publication of B=MAP (then B=MAT). Defines motivator pairs, six simplicity factors, and three prompt types. |
| Fogg, B.J. (2020) | "Tiny Habits: The Small Changes That Change Everything." Houghton Mifflin Harcourt. Chapter 3: updated B=MAP with "Prompt" replacing "Trigger" and action line threshold model; Chapters 5-6: intervention difficulty gradient (Starter Step → Scaled Habit); Chapters 14-15: behavior statement format ("After I [anchor], I will [tiny behavior]") and scaling methodology. |
| Eyal, N. (2014) | "Hooked: How to Build Habit-Forming Products." Portfolio/Penguin. Complementary habit formation framework (Hook Model). Referenced for context, not directly applied. |
| Wendel, S. (2020) | "Designing for Behavior Change: Applying Psychology and Behavioral Economics." 2nd ed. O'Reilly. Chapters 5-7: practical design patterns for behavior change interventions targeting ability barriers (simplification strategies) and motivation barriers (framing, social proof, commitment devices). Referenced for intervention design patterns. |
| Fogg, B.J. (n.d.) | "Fogg Behavior Model" (living reference, actively maintained). https://behaviormodel.org/ (accessed 2026-03-04). Canonical online resource for the B=MAP model, updated factor definitions, and current practitioner guidance. |
Sub-Skill Version: 1.5.0
Parent Skill: /user-experience v1.0.0
Constitutional Compliance: Jerry Constitution v1.0
Wave: 4 (Advanced Analytics)
SSOT: skills/user-experience/SKILL.md
Project: PROJ-022 User Experience Skill
Created: 2026-03-04