@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/cursor/ux-destructive-action-copy/skill.yaml

@@ -0,0 +1,34 @@
+name: ux-destructive-action-copy
+version: "1.0.0"
+description: Destructive action copy — irreversibility warnings, undo availability, double-confirmation patterns, cooldown messaging
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-confirmation-dialogs
+  - ux-button-cta-copy
+  - ux-microcopy-principles
+stack_signals: []
+keywords:
+  - destructive-action
+  - irreversibility
+  - undo
+  - double-confirmation
+  - data-loss
+  - warning-copy
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/ux-empty-states/SKILL.md

@@ -0,0 +1,155 @@
+# Empty States
+
+> Empty states — first-use, user-cleared, and no-results patterns that motivate action, set expectations, and turn blank screens into onramps
+
+## When to Use
+
+- Designing first-use screens when a user has no data yet (fresh accounts, new workspaces)
+- Writing zero-results messages for search or filter operations
+- Creating user-cleared states after all items are completed, deleted, or removed
+- Writing error-state empty screens (failed to load content, permission denied)
+- Building empty states for data tables, dashboards, timelines, and activity feeds
+- NOT for: loading states before data arrives (see ux-loading-states)
+- NOT for: onboarding flows and welcome sequences spanning multiple screens (see ux-onboarding-copy)
+- NOT for: error messages for system failures (see ux-error-messages)
+
+## Instructions
+
+1. **Classify the empty state type before writing any copy.** First-use, user-cleared, no-results, and error-empty each need different copy, tone, and CTA. First-use motivates: the user is new and needs to understand the value of filling the space. User-cleared celebrates: the user accomplished something (inbox zero, completed all tasks). No-results guides: the user searched and found nothing, and needs help adjusting. Error-empty explains: something failed to load and the user needs a recovery path. Writing the wrong type of copy — motivational text for a no-results screen — creates confusion and erodes trust. A "Create your first project!" message on a filtered no-results screen actively misleads users who know their projects exist.
+
+2. **Always include exactly one clear CTA.** Notion's empty page: "Press '/' for commands." GitHub's empty repository: "Create a new file or upload an existing file." The CTA must be a specific action, not a generic invitation. Multiple CTAs on an empty state create decision paralysis. If there are multiple paths forward (create, import, invite), choose the single most common one as the primary CTA and surface others as secondary text or links beneath the primary button. The hierarchy of options must be unmistakable — one primary, at most two secondary, and nothing that creates a fork without guidance.
+
+3. **Show the value of filling the empty state, not just how to fill it.** "Track your team's progress in real time" is motivating. "Click 'New Project' to create a project" is mechanical. The motivational framing answers the implicit user question: "Why would I bother?" Linear's empty issues state: "No issues. Ship fast." — the absence of issues is reframed as an achievement, and the CTA is implied by the feature's purpose. Value-first copy converts passive first-time users into active ones. Show the outcome, then the action — not the action alone. The user needs to believe the effort of creating content is worth it.
+
+4. **For no-results states, suggest specific recovery actions.** "No results for 'reciepe'" should be followed by a spelling suggestion ("Did you mean 'recipe'?"), a filter relaxation option ("Try removing the 'closed' filter"), or a browse alternative ("Browse all issues"). Never show just "No results found" without at least one recovery path. Linear's no-results state suggests broadening search terms and provides a one-click option to clear all filters. GitHub's code search suggests checking the search syntax or expanding to all branches. The recovery path must match the type of search — structured search needs filter controls, full-text search needs spelling help.
+
+5. **Keep empty state copy under 3 sentences total.** The screen is already visually sparse — a paragraph of text makes it feel heavier, not more helpful. A headline (one phrase or question), a brief explanation (one sentence, optional), and a CTA (one button or link) is the maximum. Slack's empty channel state: "This is the very beginning of the #general channel." — one sentence, historically resonant, leaves room for the first message. The brevity of the copy matches the openness of the space. If you need more than three sentences, you are writing documentation, not an empty state.
+
+6. **Use illustrations judiciously — copy must carry the message independently.** An illustration without actionable text is decoration. The empty state must work without the illustration in case it fails to load, is below the fold, or the user is using a screen reader. Write the copy as if there is no illustration. If the illustration adds meaning, reference it implicitly. Notion's empty page illustration of a hand holding a pencil works because the text explains the action — the illustration reinforces rather than replaces the message. Test the empty state with illustrations hidden — if it still communicates, the copy is doing its job.
+
+7. **Detect first-use versus returning-user context and serve different copy.** First-use empty states need motivational context because the user does not yet understand the product. Returning-user empty states — after the user has deleted all content or cleared a queue — need brevity and respect, because the user already understands the product. "All caught up." is sufficient for an inbox-zero state for an experienced user; the same screen shown to a new user needs the motivational context. When detection is not possible, default to returning-user brevity rather than first-use verbosity — experienced users are more likely to hit empty states repeatedly.
+
+8. **Error-empty states must distinguish between recoverable and unrecoverable failures.** "Couldn't load your projects. Try again." is recoverable — user can retry. "You don't have permission to view this content. Contact your workspace admin." is escalation required — user cannot self-resolve. The error-empty state must name the failure type and provide the appropriate recovery path: retry for transient errors, contact support or admin for permission issues, status page for system outages. Never show an empty state illustration with "No content here" when the actual cause is a permissions failure — the mismatch between visual tone (empty, neutral) and reality (blocked, error) misleads users.
+
+## Details
+
+### Empty State Type Matrix
+
+Selecting the wrong type creates the wrong emotional register. A celebratory tone on an error-empty screen is jarring. A motivational tone on a no-results screen is irrelevant. Always classify before writing.
+
+| Type         | User Goal           | Tone        | CTA Pattern              | Example                              |
+| ------------ | ------------------- | ----------- | ------------------------ | ------------------------------------ |
+| First-use    | Understand value    | Inviting    | Verb-noun primary action | "Create your first project"          |
+| User-cleared | Confirm completion  | Celebratory | Optional next challenge  | "Inbox zero. Enjoy the peace."       |
+| No-results   | Find alternatives   | Helpful     | Specific recovery action | "No results. Try removing filters."  |
+| Error-empty  | Recover or escalate | Empathetic  | Retry or support link    | "Couldn't load projects. Try again." |
+
+### First-Use vs Returning-User Empty States
+
+**First-use empty state:** The user has never created content. Emphasize starting value and low risk. Stripe's empty transactions table for new merchants: "No transactions yet. Create a payment link to start accepting payments." The assumption is the user is unfamiliar with the workflow. Surface the "aha moment" — show what this space will look like when populated, not just how to fill it.
+
+**Returning-user empty state:** The user deleted all content or cleared a queue. They are familiar with the product. Skip the explanation and go straight to the action. "All caught up. Create a new issue." or "No open invoices." For returning users, brevity signals respect for their expertise. A returning user who has deleted all their projects does not need to be told what a project is.
+
+When possible, detect first-use vs returning-user status to serve the appropriate version. If not detectable, default to returning-user brevity.
+
+### No-Results Recovery Patterns
+
+No-results states should offer at minimum one of these recovery paths, matched to the search type:
+
+- **Spelling suggestion:** "Did you mean 'authentication'?" with a clickable link to that search.
+- **Filter relaxation:** "Showing results in 'Engineering' only. Search all workspaces." with a one-click option.
+- **Scope expansion:** "No results in this project. Search across all projects."
+- **Browse alternative:** "No results for 'API documentation'. Browse all docs."
+- **Clear all:** A single button to reset all filters and return to the full list.
+- **Query tips:** For structured search (code, SQL, commands), show syntax help inline.
+
+Linear combines filter relaxation with browse alternatives. GitHub's search provides detailed syntax help when no results are found. The goal is to never leave the user stranded with only "No results" and a back button.
+
+### Copy Length by Empty State Location
+
+Different screens have different density tolerances for empty state copy:
+
+| Screen Type         | Headline          | Body               | CTA                 |
+| ------------------- | ----------------- | ------------------ | ------------------- |
+| Full page           | 4-8 words         | 1-2 sentences      | 1 primary button    |
+| Panel / sidebar     | 3-6 words         | 1 sentence or none | 1 link or button    |
+| Data table row area | 4-8 words         | 1 sentence or none | 1 inline link       |
+| Modal / dialog      | 3-6 words         | 1 sentence or none | 1 primary + 1 close |
+| Card / widget       | 2-4 words or icon | None               | 1 link              |
+
+### Anti-Patterns
+
+1. **The Barren Wasteland.** A completely blank screen with no guidance, no illustration, no text, and no CTA. The user stares at white space with no understanding of what the space is for or what to do next. This most commonly occurs in developer-first products where the empty state was never designed. The fix: every empty state requires at minimum a headline and a CTA — a one-sentence explanation of what the user can create or do in this space is the minimum viable empty state.
+
+2. **The Instruction Manual.** A paragraph or more of explanation about how to use the feature in the empty state, overwhelming the user at the moment they need the most encouragement. "Welcome to Projects! Projects help you organize your work into containers. You can add tasks, set deadlines, invite team members, and track progress. To get started, click the 'New Project' button in the top right corner..." This is documentation, not an empty state. Condense to one phrase, one optional sentence, one CTA.
+
+3. **The Sad Illustration.** A decorative illustration (an empty box, a sad robot, a blank page with question marks) with no actionable text, no CTA, and no explanation. The illustration communicates "nothing is here" visually but gives the user nowhere to go. Empty state illustrations should always be accompanied by text that explains what should be here and how to add it. An illustration without text is visual wallpaper — it aestheticizes the problem without solving it.
+
+4. **The Wrong Type.** Using first-use motivational copy for a no-results state, or user-cleared celebratory copy for an error-empty state. "Create your first project!" shown when all projects are filtered by "Archived" actively misleads the user into thinking they have no projects. The empty state type must match the actual situation. If the product cannot detect the difference between first-use and filtered-empty, default to neutral language that works for both: "No projects to show" with filter controls visible is better than "Create your first project" when projects may exist but are hidden.
+
+### Real-World Examples
+
+**Notion's Blank Page Experience.** Notion's empty page state uses a single instructional line: "Press '/' for commands" with a secondary line "Start writing, or drag files here." The minimalism matches the product's philosophy that a blank page is potential, not a problem. The hint teaches the primary interaction model (the slash command) in context. Notion removes the hint after the user has used it a few times, transitioning to true blank-slate for experienced users. This adaptive behavior — showing motivation to new users, then getting out of the way — is the ideal empty state lifecycle.
+
+**GitHub's Empty Repository Setup.** GitHub's empty repository page is the gold standard for first-use empty states in developer tools. It provides the exact git commands to initialize and push a new repository, copy buttons for each command block, and multiple paths (new file, README, .gitignore, upload files). The technical nature of the content means more text is appropriate here than in most empty states. GitHub trusts its users enough to show them commands rather than hiding complexity behind a "Get started" button. The empty state teaches the workflow rather than abstracting it.
+
+**Slack's Empty Channel State.** When a channel is first created, Slack shows: "This is the very beginning of the #[channel-name] channel." This simple message sets context (this is the start), establishes ownership (this is your channel), and creates a sense of occasion. No CTA is needed — the user knows what to do (send a message). The message disappears once the first message is sent — it is contextually relevant only at the moment of creation.
+
+**Linear's No-Results Search.** Linear's search returns "No results for '[term]'" with two recovery paths: clear the search and see all results, or search across all teams. The zero-results state also surfaces keyboard shortcuts to refine the search. Linear avoids suggestions and spelling corrections because its search is structured (searching issues, projects, members) rather than full-text — the recovery paths it offers match its actual capabilities rather than importing patterns from full-text search that would not work here.
+
+## Source
+
+- NNGroup — "The Power of Empty States" (2017), https://www.nngroup.com/articles/empty-state-mobile-app-nice-to-have/
+- Google Material Design — Empty states guidance, https://m3.material.io/foundations/layout/understanding-layout/parts-of-a-layout
+- Invision — "How to Design Empty States," https://www.invisionapp.com/inside-design/empty-state-design/
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), empty state and zero-data patterns
+- Hulick, S. — _The Elements of User Onboarding_ (2013), first-use and value-first patterns
+
+### Empty States in Feature-Gated Contexts
+
+When an empty state is caused by a plan or permissions limitation — not the absence of data — the copy must address the actual cause:
+
+**Plan gate empty state:** "Analytics are available on the Pro plan. Upgrade to see your traffic data →." The copy names what is missing (analytics), explains why (Pro plan), and offers the next step (upgrade). Do not show a generic empty state illustration with "No data yet" — the user may have data, they just cannot see it. Misrepresenting a plan gate as an absence of data confuses users and erodes trust.
+
+**Permission gate empty state:** "You don't have access to this workspace. Contact your admin to request access." The copy distinguishes between "no content exists" and "you can't see the content that exists" — a critical distinction for user mental models. GitHub shows "You need to be a collaborator to view this repository" — clear, accurate, with an implicit next step (become a collaborator).
+
+The rule: always tell the user why the space is empty, not just that it is empty. The reason determines the recovery path — creation, upgrade, or permission request.
+
+## Process
+
+1. Classify the empty state as first-use, user-cleared, no-results, or error-empty — confirm the classification matches the actual user situation.
+2. Write a headline of 3-8 words that names the type of content that belongs here and its value.
+3. Add one optional sentence of context if the headline alone is insufficient.
+4. Write a single specific CTA (verb-noun) as a button or link.
+5. For no-results states, add at least one recovery path: spelling suggestion, filter relaxation, or scope expansion.
+
+### Empty State Copy Audit Checklist
+
+Before shipping an empty state, verify each item:
+
+| Check                                               | Pass Criteria                                              |
+| --------------------------------------------------- | ---------------------------------------------------------- |
+| Type classified                                     | First-use, user-cleared, no-results, or error-empty        |
+| Copy works without illustration                     | Message is comprehensible with image removed               |
+| Exactly one primary CTA                             | Single specific verb-noun action, not two or more          |
+| Under 3 sentences total                             | Headline + optional body + CTA                             |
+| No results state has a recovery path                | Filter clear, scope expand, or spelling suggestion present |
+| Error-empty distinguishes recoverable vs escalation | "Try again" vs "Contact admin" based on error type         |
+| Value shown, not just instructions                  | Answers "why bother?" not just "how to"                    |
+| First-use vs returning-user context respected       | Motivational for new, brief for returning                  |
+
+A blank or generic empty state is a missed opportunity in every product. Empty states occur most often when users are new (high value moment) or when search fails (high frustration moment) — both moments where copy quality has outsized impact on whether users continue or abandon.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Every empty state is classified as one of the four types and uses the appropriate tone and CTA pattern.
+- Empty state copy is 3 sentences or fewer, including a single specific CTA.
+- No-results states include at least one recovery path (spelling correction, filter relaxation, or browse alternative).
+- First-use empty states lead with the value of the content, not just instructions for how to create it.
+- Empty state copy is independently comprehensible without relying on an illustration.
+- Error-empty states distinguish between recoverable failures (retry) and unrecoverable failures (contact admin / support).

package/dist/agents/skills/cursor/ux-empty-states/skill.yaml

@@ -0,0 +1,36 @@
+name: ux-empty-states
+version: "1.0.0"
+description: Empty states — first-use, user-cleared, and no-results patterns that motivate action, set expectations, and turn blank screens into onramps
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-microcopy-principles
+  - ux-onboarding-copy
+  - ux-writing-for-scanning
+  - design-empty-error-states
+  - design-loading-patterns
+stack_signals: []
+keywords:
+  - empty-states
+  - first-use
+  - zero-data
+  - no-results
+  - onboarding
+  - blank-slate
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/ux-error-messages/SKILL.md

@@ -0,0 +1,159 @@
+# Error Messages
+
+> Error messages — what went wrong, why it matters, how to fix it, the three-part error pattern for clear, actionable error communication
+
+## When to Use
+
+- Writing form validation error messages (inline, summary banner, or toast)
+- Composing system error messages (500 errors, timeouts, connectivity failures)
+- Creating API error responses that surface to end users
+- Writing permission-denied or authorization error text
+- Handling field-level and page-level validation across complex forms
+- NOT for: error logging or developer-facing error messages (stack traces, debug output)
+- NOT for: empty state copy shown when no content exists (see ux-empty-states)
+- NOT for: severity tier selection and escalation patterns (see ux-error-severity)
+
+## Instructions
+
+1. **Use the three-part pattern: what went wrong, why, how to fix it.** Every useful error message answers three questions: What failed? Why did it fail? What should the user do now? Stripe's payment decline: "Your card was declined. The issuing bank did not approve the transaction. Try a different payment method or contact your bank." Each clause serves one of the three purposes. A message with only "Card declined" leaves users stranded. A message with all three parts gives them a path forward. For system errors where the cause is unknown, omit the "why" rather than guessing — "We couldn't save your changes. Try again in a few minutes" is honest and actionable even without a known cause.
+
+2. **Place errors inline next to the field that caused them.** Error messages must appear in the same visual zone as the problem. GitHub highlights the specific field in red with the error message directly below it. A summary banner ("3 fields have errors") without inline messages requires the user to hunt for problems. Use both: inline messages for each field plus a page-level summary that links to each field, especially on long forms. Never display only a top-of-page summary for field-specific errors — the user should not have to scroll from the top banner back down to the field to understand what needs fixing.
+
+3. **Write errors in plain language — never expose technical codes or stack traces.** "Something went wrong" is better than "Error 500: Internal Server Exception" but "We couldn't save your changes. Try again in a few minutes." is better than both. Users do not understand HTTP codes, database exceptions, or stack traces. Translating technical failures into human language is the error writer's primary job. Notion translates sync conflicts: "Someone else edited this page. We've saved both versions — choose which to keep." No mention of merge conflicts or version hashes. Every technical error should be caught at the UI layer and replaced with a human sentence.
+
+4. **Use the same voice as the rest of the product — errors are not exempt from tone guidelines.** Slack's error messages maintain conversational tone even when things break: "Hmm, we can't reach our servers. Check your connection." Stripe maintains professional directness: "Your account is currently under review." Error states are the product's worst moment — a tonal mismatch makes them worse. If the product uses "you" and contractions elsewhere, use them in errors too. Reserve formal, impersonal language only if the product's baseline voice is formal and impersonal. An error that sounds robotic in a conversational product signals that the error was never reviewed by a writer.
+
+5. **Tell the user what to do next — every error must have a recovery path.** If user action can fix the error, name that action specifically. If no user action can fix it, say when the team is investigating, provide a status page link, or state when to retry. "Our servers are down. Check status.stripe.com for updates." is better than "Service unavailable." GitHub provides a link to their status page from every server error. Never leave the user with a problem and no path forward — even "Contact support" or "Try again later" is a recovery path. A dead-end error message is a product failure, not just a writing failure.
+
+6. **Do not blame the user.** Attribute the problem to the input or the system, never to the person. "That password is too short" not "You entered an invalid password." "This email is already registered" not "You already have an account." "The file is too large" not "You uploaded a file that's too big." Passive attribution to the object ("the file," "that password") is gentler than active attribution to the user ("you uploaded," "you entered"). Linear: "This name is already taken" not "You chose a name that's already in use." The user is already frustrated by the error; do not layer on fault attribution.
+
+7. **Be specific about constraints before and after errors occur.** "Password must be at least 8 characters, include one uppercase letter and one number" — show this as helper text before errors, and reference the specific unmet constraint in the error: "Password needs at least one number." Stripe shows the exact card requirement that was not met. Specificity eliminates the guessing game of "what does 'invalid password' actually mean?" and gives users actionable information they can use immediately to fix the issue. Vague errors like "Invalid input" require the user to guess what specifically is wrong.
+
+8. **Differentiate between field-level and page-level errors with distinct patterns.** Field-level messages are brief and inline: "Email address is required." Page-level messages describe the aggregate: "2 fields need your attention before continuing." For forms with many fields, a sticky page-level banner that links to each error field saves users from scrolling to find problems. Shopify's checkout shows a count-and-anchor pattern: "Please fix 2 errors below" with anchor links to each field. Both levels serve different navigation needs — page-level for orientation, field-level for resolution.
+
+## Details
+
+### Error Message Anatomy
+
+The three-part error structure maps directly to user cognitive needs:
+
+| Part       | Question Answered | Example                                      | Required?  |
+| ---------- | ----------------- | -------------------------------------------- | ---------- |
+| What       | What failed?      | "Your card was declined."                    | Always     |
+| Why        | What caused it?   | "The issuing bank did not approve."          | When known |
+| How to fix | What to do next   | "Try a different card or contact your bank." | Always     |
+
+For user-caused errors (form validation), the "why" is usually the constraint: "Password must include a number." For system errors, the "why" is the cause when known ("Our servers are temporarily unavailable") or omitted when not. The "how to fix" must always be present unless nothing can be done, in which case offer a status path ("Check status.stripe.com").
+
+### Error Placement Decision Matrix
+
+Selecting the wrong placement undermines the error's effectiveness. A transient network error in a blocking modal is disproportionate. A session expiration in a toast that auto-dismisses is a security and usability failure.
+
+| Error Type               | Placement            | Persistence     | Character Limit       |
+| ------------------------ | -------------------- | --------------- | --------------------- |
+| Field validation         | Inline, below field  | Until corrected | 1-2 short sentences   |
+| Multi-field form error   | Page banner + inline | Until corrected | Count + links to each |
+| System error (transient) | Toast / snackbar     | 5-8 seconds     | 120 characters        |
+| System error (blocking)  | Modal dialog         | Until dismissed | 2-3 sentences         |
+| Inline save failure      | Inline near trigger  | Until resolved  | 1 sentence + action   |
+
+### Error Tone Calibration by Error Category
+
+Error tone should match severity and the product's baseline voice:
+
+- **Field validation:** Calm, instructional, non-alarming. "Email address is required." Present tense, no exclamation.
+- **User mistake (recoverable):** Direct but gentle. "This email is already registered. Try logging in instead."
+- **System error (transient):** Empathetic, explains situation. "We're having trouble connecting. We'll keep trying."
+- **System error (persistent):** Direct with status path. "Our service is unavailable. Check status.stripe.com."
+- **Destructive / irreversible:** Clear, unambiguous, never softened. "This action cannot be undone."
+
+### Writing Error Messages for Async Operations
+
+Async operations — uploads, exports, background syncs — require a different error model. The user has moved on by the time the error occurs, so the error must re-establish context:
+
+- **Name the operation that failed:** "Your CSV export failed." not "Export failed."
+- **State when it failed:** "Your export failed 2 minutes ago." for non-blocking async errors.
+- **Offer a retry path:** "Try exporting again" should be a button, not just text.
+- **Confirm what was saved vs lost:** "Your changes were saved, but the export did not complete."
+
+Stripe's export errors follow this pattern. GitHub's Actions failure notifications include the step that failed, the exit code reason in plain language, and a direct link to the failing run. Async error messages must be complete enough to stand alone — the user cannot see the original trigger.
+
+### Anti-Patterns
+
+1. **The Cryptic Code.** Exposing error codes, technical exceptions, or stack traces directly to users. "Error 0x80004005: Unspecified error," "NullPointerException at line 247," "ECONNREFUSED." Users cannot act on these. The fix: catch all errors at the UI layer and translate into human language. The technical code can appear in a collapsed "details" section for support teams, but never as the primary message. Showing raw technical output signals that the error path was never designed — it was just left unhandled.
+
+2. **The Blame Game.** Error messages that explicitly or implicitly fault the user. "You entered an invalid value." "You chose a username that is already taken." "Your session expired because you were inactive." Reframe: name the issue without a subject ("That username is taken"), or use the object as subject ("The session timed out after 30 minutes of inactivity"). The user already feels frustrated — do not add guilt. Blaming the user also trains them to distrust the product when errors occur.
+
+3. **The Dead End.** Error messages with no recovery path, no next step, no action. "Something went wrong." "Error occurred." "Unable to process your request." These messages tell the user what happened (minimally) but offer no resolution. Every error must have at minimum one of: a specific action the user can take, a link to support, a status page URL, or a "Retry" button. A dead-end error is the product equivalent of a locked door with no sign explaining how to get in.
+
+4. **The Generic Catch-All.** Using a single vague error for all failure modes — "Something went wrong, please try again" — regardless of whether the issue is a network timeout, validation failure, permission error, or server crash. Each error type warrants a distinct message. A form validation error ("Password is too short") and a connectivity error ("We can't reach our servers") are completely different problems requiring completely different responses. Generic catch-alls hide useful debugging information from users and signal that error states were not designed intentionally.
+
+### Real-World Examples
+
+**Stripe's Payment Error Flow.** Stripe distinguishes between card-specific and account-level errors with different message patterns. Card decline: "Your card was declined. The issuing bank did not approve this charge. Try a different card or contact your bank." Incorrect CVV: "Your card's security code is incorrect. Check the 3-digit number on the back of your card." Each message names the exact problem and provides a specific next step. Stripe never shows raw decline codes to end users — those go only to the merchant dashboard. Stripe's error taxonomy is exhaustive: over 30 distinct decline reasons each with a unique user-facing message.
+
+**GitHub's Form Validation.** GitHub highlights error fields with a red border and places the error message directly below the field. Repository name conflict: "Name has already been taken." Username requirements: "Username may only contain alphanumeric characters or single hyphens, and cannot begin or end with a hyphen." GitHub relies entirely on inline messages, keeping the feedback localized to the problem field. When multiple fields fail, GitHub focuses on the first field — not all at once — to avoid overwhelming the user.
+
+**Notion's Sync Error Handling.** Notion surfaces sync conflicts with a non-blocking notification: "Someone else edited this page while you were working. We've kept both versions — choose which to keep." This three-part message names what happened, explains the consequence (both versions preserved), and provides a clear action (choose). The tone matches Notion's calm, collaborative voice. Notion avoids panic language like "WARNING: conflict detected" — the situation is resolved, so the message is calm.
+
+**Shopify's Checkout Errors.** Shopify uses a page-level error count ("Please fix 2 errors to continue") with anchor links to each field, combined with inline messages below each field. This dual-layer approach is the gold standard for long or multi-section forms. The count gives scope; the anchor links eliminate scrolling; the inline messages provide specific context at the point of correction. Shopify also retains the user's valid data across the error — the fields that were correct remain filled.
+
+## Source
+
+- NNGroup — "Error Message Guidelines" (2001, updated 2020), https://www.nngroup.com/articles/error-message-guidelines/
+- Google Material Design — Text field error states, https://m3.material.io/components/text-fields/guidelines
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), ch. 7: Error Messages
+- Nielsen, J. — "User Interface Design Heuristics #9: Help users recognize, diagnose, and recover from errors" (1994)
+- Podmajersky, T. — _Strategic Writing for UX_ (2019), error and failure state patterns
+- Wroblewski, L. — _Web Form Design_ (2008), inline validation and error placement research
+
+### Internationalizing Error Messages
+
+Error messages that work in English may fail in other languages. Design error copy for localization:
+
+- **Avoid string concatenation:** "Your " + fieldName + " is invalid" breaks in languages with different word order. Write complete sentences: "That email address is not valid."
+- **Avoid relative time expressions:** "Please try again in a few minutes" is difficult to localize consistently. Use explicit guidance: "Please try again in 5 minutes" or "Please try again later."
+- **Gender-neutral phrasing:** "Your account has been locked" avoids gendered constructions that may not translate directly.
+- **Avoid idioms:** "Something went sideways" does not translate. "Something went wrong" does.
+- **Test with German:** German compound words and longer translations regularly reveal UI overflow issues in error message containers. If the error container holds German error copy, it will hold all major languages.
+
+Error messages that are designed for localization from the start are shorter, more literal, and easier for translators — which is also a benefit for English-language users who benefit from the same clarity.
+
+## Process
+
+1. Identify whether the error is field-level, form-level, or system-level — each requires a different placement and pattern.
+2. Write the three-part message: what failed, why it failed (when known), what to do next.
+3. Remove any technical language, error codes, or jargon — translate to user vocabulary.
+4. Verify the tone matches the product's voice guidelines and does not assign blame to the user.
+5. Confirm the message includes a recovery action or link — no dead ends.
+
+### Error Message Review Checklist
+
+Before shipping any error message, verify each item:
+
+| Check                      | Pass Criteria                                             |
+| -------------------------- | --------------------------------------------------------- |
+| Three-part structure       | What + why (if known) + how to fix                        |
+| No technical language      | No codes, exceptions, or stack traces visible             |
+| Placement correct          | Field-level inline; system-level in appropriate component |
+| No user blame              | No "you entered," "you chose," "your mistake"             |
+| Recovery path present      | Action button, retry link, or status URL                  |
+| Tone matches product voice | Same voice as success states and onboarding               |
+| Constraint specificity     | Names the specific unmet constraint, not "invalid"        |
+| Async context preserved    | Async error re-establishes what was being processed       |
+
+Failing any item in this checklist means the error message needs revision before shipping. Incomplete error messages erode user trust in proportion to their frequency — in a product where errors happen often (form-heavy workflows, developer tools), error message quality directly affects overall product quality perception.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- All error messages follow the three-part structure: what, why (when known), how to fix.
+- Field-level errors appear inline next to the field, not only in a top-of-page summary.
+- No error message exposes technical codes, exception names, or stack traces to users.
+- Every error message includes a recovery action, retry option, or status link — no dead ends.
+- Error tone matches the product's voice guidelines and avoids attributing blame to the user.
+- Async operation errors re-establish context and include a specific retry or escalation path.

package/dist/agents/skills/cursor/ux-error-messages/skill.yaml

@@ -0,0 +1,35 @@
+name: ux-error-messages
+version: "1.0.0"
+description: Error messages — what went wrong, why it matters, how to fix it, the three-part error pattern for clear, actionable error communication
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-microcopy-principles
+  - ux-voice-tone
+  - ux-plain-language
+  - design-empty-error-states
+  - design-feedback-patterns
+stack_signals: []
+keywords:
+  - error-messages
+  - validation
+  - user-feedback
+  - error-recovery
+  - inline-errors
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/ux-error-severity/SKILL.md

@@ -0,0 +1,155 @@
+# Error Severity Communication
+
+> Error severity communication — calibrating error tone to severity, from field validation to system failure to data loss
+
+## When to Use
+
+- Deciding between warning, error, and critical severity for a message
+- Writing data loss or irreversible action warnings that require urgent communication
+- Calibrating tone for field validation errors versus system outage messages
+- Designing error hierarchies for forms or dashboards with multiple issue types
+- Building escalation sequences for trial expiration, quota warnings, and usage alerts
+- NOT for: error message content and structure (see ux-error-messages)
+- NOT for: destructive action confirmation dialogs (see ux-destructive-action-copy)
+- NOT for: notification component selection and urgency calibration (see ux-notification-copy)
+
+## Instructions
+
+1. **Map severity to visual and textual weight — they must always match.** Field validation is calm and instructional. System errors are direct and factual. Data loss warnings are urgent and specific. The text must reinforce what the visual design communicates — using alarming language with a blue informational icon, or casual language with a red critical indicator, creates cognitive dissonance that undermines user trust. A red error badge on a benign "email already subscribed" message trains users to distrust the severity system. Severity levels must be consistent: the same category of error should always read the same way, everywhere in the product.
+
+2. **Use a four-tier severity model: info, warning, error, critical.** Each tier has distinct copy patterns that pair with visual treatment. Info (blue): supplemental context the user should know but that requires no action. Warning (amber): something that needs attention but does not block progress — the user can continue but should be aware. Error (red): something that failed and blocks a specific action — user must take action to proceed. Critical (red + icon + blocking): data loss, security issues, or irreversible states requiring immediate action — the user cannot proceed without addressing this. AWS Console uses all four tiers with consistent styling and copy conventions across hundreds of services.
+
+3. **Match punctuation and sentence structure to severity.** Informational messages use lowercase, periods, and suggest rather than demand. "Your draft is saved automatically." Warnings use direct statements that name the consequence. "This action will affect 47 team members." Error messages use imperative recovery instructions. "Payment failed. Try a different card." Critical messages use imperative sentences and explicit consequence statements. "This will permanently delete all data. This cannot be undone." The register escalates with severity — critical messages should feel heavier in both visual weight and grammatical authority than info messages.
+
+4. **Never escalate minor issues to high severity.** "Password too short" is not a critical error. "File successfully uploaded" is not a warning. Overuse of red styling, all-caps text, warning icons, or alarming language on routine events trains users to ignore real warnings. This is the severity version of the crying wolf effect — when everything looks urgent, nothing is urgent. Linear uses green checkmarks for success, amber for warnings about usage limits, and red only for genuine errors like failed syncs or authentication failures. Reserve the critical tier for events that genuinely warrant it.
+
+5. **For data-loss scenarios, name the specific data at risk.** "Your unsaved changes will be lost" is better than "Are you sure?" but "Your 3 unsaved comments and 1 uploaded image will be permanently deleted" is best. Specificity creates genuine understanding of consequence. Vague warnings like "data may be affected" are routinely dismissed because users cannot assess the actual impact. Figma's autosave conflict dialog names the specific edits from each editor that would be overwritten. GitHub's repository deletion confirmation names the repository and lists what is included: "All forks, pull requests, issues, and wikis will also be deleted."
+
+6. **System errors should communicate timeline when possible.** Users need to know whether to retry now, retry later, or wait for a fix. "We're looking into this" (investigating, indeterminate timeline), "Try again in a few minutes" (transient, short wait), "Service unavailable until 3:00 PM EST" (known resolution window), "Follow @status for updates" (unknown, ongoing monitoring). VS Code's extension marketplace shows degraded-service banners with specific context about what is affected and what the team is doing about it. A system error without a timeline leaves users unable to decide whether to wait, retry, or use an alternative.
+
+7. **Escalate severity language as risk accumulates — not just visual treatment.** Trial expiration warnings should escalate in copy intensity, not just color or icon. "Your trial ends in 14 days" (info) → "Trial ends in 3 days. Upgrade to keep your data" (warning) → "Trial ends tomorrow. Add billing now or lose access" (error) → "Your trial has ended. Export your data before it's deleted in 24 hours" (critical). Stripe, GitHub, and Figma all use this escalation pattern for quota and billing warnings. Each stage increases specificity and urgency in both the visual and copy treatment simultaneously.
+
+8. **Provide recovery actions proportional to severity tier.** Info tier recovery is optional: a "Learn more" link or a dismiss button. Warning tier recovery is a single clear action: "Enable backup" or "Upgrade plan." Error tier recovery is a specific instruction with a direct action button: "Try again" or "Switch card." Critical tier recovery requires explicit, high-friction confirmation: typing the project name, checking a checkbox, or clicking a prominently labeled destructive button. The friction of the recovery action should match the severity of the error — low friction for low severity, high friction for critical severity.
+
+## Details
+
+### Severity Tier Matrix
+
+The tier determines both the visual component (snackbar, banner, modal, inline) and the copy register. Info messages can appear in snackbars. Critical messages require blocking modals with explicit confirmation.
+
+| Tier     | Visual     | Persistence    | Copy Pattern                                 | Example                                       |
+| -------- | ---------- | -------------- | -------------------------------------------- | --------------------------------------------- |
+| Info     | Blue icon  | Dismissable    | Supplemental statement, lowercase            | "Your account is set to send weekly digests." |
+| Warning  | Amber icon | Persistent     | Direct statement of risk, period             | "Enabling this removes 2FA protection."       |
+| Error    | Red icon   | Until resolved | Named failure + recovery action              | "Payment failed. Try a different card."       |
+| Critical | Red block  | Blocking       | Named consequence + irreversibility + action | "This deletes all 47 projects permanently."   |
+
+### Escalation Patterns
+
+Severity should escalate when frequency or cumulative impact increases — not by time alone. The user's decision not to act is the trigger for escalation:
+
+- **First occurrence:** Info or warning level. "Your trial ends in 14 days."
+- **Second occurrence / midpoint:** Warning level with more urgency. "Trial ends in 7 days. Upgrade to keep your data."
+- **Final occurrence / threshold:** Error or critical level. "Trial ends tomorrow. Add billing now to prevent data loss."
+- **Post-threshold:** Critical with immediate action. "Your access has ended. Export data before deletion in 24 hours."
+
+This pattern is used by Stripe, GitHub, and Figma for trial expiration, usage limits, and quota warnings. Each message escalates in severity, visual treatment, and copy directness. Escalation copy must name the specific consequence at each stage — "data loss," "access lost," "files deleted" — so users understand why escalation is happening.
+
+### Recovery Urgency Mapping
+
+Recovery instructions must match the urgency of the error:
+
+- **Info:** Optional follow-up. "Learn more" or "Manage preferences."
+- **Warning:** Clear action with low friction. "Upgrade plan" or "Enable backup."
+- **Error:** Specific recovery step. "Try again" or "Use a different method."
+- **Critical:** Immediate, high-friction action required. "Confirm deletion by typing the project name below."
+
+Recovery actions at the critical tier should require active confirmation — a checkbox, a typed confirmation, or an explicit button press. Auto-recovery (the system fixes it silently) is acceptable for info and warning tiers. For error and critical tiers, the user must take the recovery action explicitly so they understand what happened and are not surprised by the outcome.
+
+### Severity Calibration Checklist
+
+Before assigning a severity tier, answer these questions:
+
+1. Does this block the user from continuing their primary task? (No → Info or Warning; Yes → Error or Critical)
+2. Is there a risk of data loss or irreversible action? (No → Info or Warning; Yes → Critical)
+3. Is user action required to resolve? (No → Info; Yes → Warning, Error, or Critical based on blocking status)
+4. Will the system recover automatically? (Yes → Info or Warning; No → Error or Critical)
+5. Has the user already ignored a lower-severity version of this message? (Yes → escalate one tier)
+
+### Anti-Patterns
+
+1. **The Boy Who Cried Wolf.** Every error styled as critical — red icons, bold text, alarming language — even for routine validation like "password too short" or "email already in use." When the severity design is overused, users stop reading error messages. They click the prominent button to dismiss and move on. Reserve red and blocking patterns for genuine errors. Slack uses this well: routine validation is subtle (red border, small inline text), while account-level issues use prominent banners. If every error looks like an emergency, real emergencies are ignored.
+
+2. **The Calm Catastrophe.** Data loss warnings that use the same casual tone as field validation messages. "You might lose some changes" uses hedged language ("might," "some") for what could be a significant data loss event. GitHub's repository deletion confirmation does the opposite: it names exactly what will be lost, states "This action CANNOT be undone," and requires typing the repository name before proceeding. When data is genuinely at risk, the copy must reflect the stakes unambiguously. Hedging language on critical messages is more dangerous than no warning at all.
+
+3. **The Severity Mismatch.** Red error styling on informational messages like "Email already subscribed (you'll continue to receive emails)" or warnings styled as errors when no action is blocked. The mismatch between visual severity (red) and actual consequence (information, not a failure) confuses users and erodes their ability to calibrate the importance of future messages. Visual severity and copy severity must always be consistent — if the visual says "critical," the copy must name a critical consequence. If the consequence is minor, use a minor-tier visual component.
+
+4. **The Undifferentiated Escalation.** Using only visual treatment to escalate (changing from blue to amber to red) without escalating the copy. "Free plan" in blue, then "Free plan" in amber, then "Free plan" in red — same text, changing color — communicates nothing specific about why the urgency is increasing. Copy must escalate alongside visuals: "14 days remaining" → "3 days remaining. Upgrade to keep access" → "Access ends tomorrow." The user should understand from the copy alone, without the visual treatment, that the situation has become more urgent.
+
+### Real-World Examples
+
+**Figma's Autosave Conflict Resolution.** When two editors modify the same frame simultaneously, Figma shows a warning-tier message: "Someone else made changes to this file. We've created a duplicate to preserve your work." The tone is calm because data is not lost — both versions are preserved. If instead Figma had lost one version, the message would escalate to critical: "Your changes from the last 10 minutes could not be saved due to a conflict." The distinction is consequential: the first requires a choice, the second requires recovery. Figma's severity calibration turns on whether data is lost, not just whether a conflict occurred.
+
+**AWS Console's Tiered Alert System.** AWS uses four distinct alert components across its console: blue informational banners for best-practice suggestions, amber warnings for configuration issues that could cause problems, red error banners for failures requiring attention, and blocking red modals for destructive operations like terminating production instances. Each tier uses consistent language patterns across all AWS services. An error banner always names the failed resource, states the error type, and links to documentation. This consistency means experienced AWS users can triage alerts by visual tier before reading the content — which is the goal of any severity system.
+
+**VS Code's Problem Panel Severity Levels.** VS Code's Problems panel sorts issues by severity (errors > warnings > info) and uses distinct iconography for each. Error messages in the panel name the specific file and line, describe the issue precisely ("Property 'id' does not exist on type 'User'"), and link to the offending code. Warning messages use softer language ("Consider using const instead of let") because they do not block compilation. The panel's sorting by severity means users address blockers first, then non-blocking issues — a natural triage workflow enforced by the severity system itself.
+
+**Stripe's Quota and Billing Escalation.** Stripe's usage-based billing warnings escalate from info (first approach to limit), to warning (near limit), to error (at limit, some features blocked), to critical (over limit, service may be interrupted). Each tier's message escalates in specificity: "Approaching your monthly limit" → "80% of your monthly limit used" → "Monthly limit reached. New charges are being blocked" → "Account suspended. Contact support to restore access." The copy names the specific consequence at each stage, giving merchants the information they need to act proportionally to the urgency.
+
+## Source
+
+- NNGroup — "Indicators, Validations, and Notifications: Pick the Correct Communication Option" (2015), https://www.nngroup.com/articles/indicators-validations-notifications/
+- Apple Human Interface Guidelines — Alerts and notifications, https://developer.apple.com/design/human-interface-guidelines/alerts
+- Google Material Design — Snackbar, banner, and dialog severity guidelines, https://m3.material.io/components/snackbar/guidelines
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), severity calibration in error copy
+- Podmajersky, T. — _Strategic Writing for UX_ (2019), escalation patterns and severity tiers
+
+### Writing Severity Copy for Different User Expertise Levels
+
+Severity communication must account for the user's expertise with the domain, not just the technical severity of the event:
+
+- **Expert users** in developer tools can tolerate more technical specificity in error copy. "Build failed: TypeScript compilation error in auth.ts:47" is appropriate for a VS Code user. The severity is communicated by the error tier, not by adding alarm language.
+- **Non-expert users** in consumer products need consequence-focused language. "Your payment didn't go through" communicates severity through consequence, not technical codes.
+- **Mixed audiences** (Stripe, which serves both technical integrators and non-technical business users) need severity tiers that work both ways: the visual tier communicates to non-readers, the copy details communicate to readers.
+
+The severity tier must work visually before the user reads the copy. Experienced users triage by visual tier; new users read. Both pathways must lead to the same understanding of severity.
+
+## Process
+
+1. Classify the error into one of the four severity tiers (info, warning, error, critical) based on whether it blocks action and whether it risks data loss.
+2. Select the appropriate visual component for the tier — inline text, snackbar, banner, or blocking modal.
+3. Write copy that matches the tier's register: supplemental for info, direct for warning, recovery-focused for error, urgent-specific for critical.
+4. Verify the visual styling and copy severity are consistent — no alarming language with calm visual treatment, or vice versa.
+5. Check whether the error is part of an escalation sequence and calibrate the copy to the current stage of that sequence.
+
+### Severity Audit: Common Misclassifications
+
+Products commonly misclassify these events — use this table to calibrate:
+
+| Event                           | Common Misclassification | Correct Tier   | Reason                                              |
+| ------------------------------- | ------------------------ | -------------- | --------------------------------------------------- |
+| Password too short (validation) | Error                    | Field inline   | Not blocking the session, only the submit action    |
+| Email already registered        | Error                    | Field inline   | Recoverable — user can log in instead               |
+| File exceeds size limit         | Error                    | Warning        | Blocks the specific upload but not other actions    |
+| Subscription payment failed     | Warning                  | Error          | Blocks access — requires immediate recovery action  |
+| Repository about to be deleted  | Warning                  | Critical       | Irreversible — requires maximum friction            |
+| Trial ends in 14 days           | Critical                 | Info           | No immediate action required; 14 days is not urgent |
+| Trial ends tomorrow             | Info                     | Error/Critical | Requires action; delay has real consequence         |
+| Background sync delay           | Error                    | Info           | Not blocking user; user can continue working        |
+| Deployment failed on production | Warning                  | Error          | Production failures require immediate attention     |
+
+Reviewing this table against your product's existing error states will surface the most common misclassifications. The pattern: products over-use red for validation and under-use red for billing and data loss events.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Each error or warning uses one of the four severity tiers with appropriate visual and copy treatment.
+- Critical severity messages name the specific data at risk, state irreversibility, and require explicit user action.
+- No routine validation error (password too short, field required) uses critical or error styling.
+- System errors include timeline information when available (retry timing, status link, incident status).
+- Escalation sequences increase severity language at each stage, not only visual treatment.
+- Visual severity and copy severity are always consistent — no mismatch between the component used and the language used.