Intuitive Software Design

View saved version →

---
name: behavioral-evaluation
description: Prepare or assess controlled evaluations of Intuitive Software Design agent outputs using realistic UI task fixtures and separate acceptance criteria. Use when testing plugin quality or comparing plugin versions; not for scoring a live product's usability or treating agent results as human research.
---
<!-- Copyright 2026 ArcanEdge AI. Licensed under Apache-2.0; preserve this notice when redistributing. Source: https://github.com/ArcanEdge-AI/intuitive-software-design -->

# Behavioral Evaluation

Evaluate whether this plugin changes an agent's decisions in useful, evidence-grounded ways. Package validation, agent-output quality, and human usability are different results. Keep the authoritative [standard](../intuitive-software-design/references/intuitive-software-design-standard.md) as the interpretation boundary.

## Prepare a bounded comparison

Establish the question, candidate version, baseline if any, case selection, permitted resources/actions, and evaluation budget. Preparing prompts is not authority to dispatch models, spawn helpers, spend credits, access a live system, or publish results. Use the user's authorized route/settings for actual execution; record model, effort, tools, and environment rather than assuming defaults.

Use [the case index](references/case-index.md) to choose relevant fixture packets. Every packet contains a task and raw artifacts; [the assessor rubric](references/assessor-rubric.md) contains acceptance criteria. For a quality evaluation, provide the execution task only the selected packet and plugin, not the rubric, expected diagnosis, or prior answer. Read the rubric when assessing outputs, not as additional task context. Do not load all cases by default.

Cases are fictional and static. They measure reasoning from the supplied artifacts, not operation of a real UI. For runtime evaluations, separately record authorized fixture setup, actual interactions, and state evidence.

## Execute without contaminating the result

Use a fresh task for each condition where feasible. Keep raw task, artifacts, model/effort, tool availability, and output requirements comparable. State any difference that could explain a result. Do not give the candidate extra research or the baseline the candidate's instructions. Record the exact package version and skill availability; a source-path test is not installed-catalog activation.

Preserve the raw answer and relevant tool evidence before assessing it. Do not rewrite a response into a passing one. If execution cannot proceed, record Not run and the blocker instead of a result. A single uncontrolled example is exploratory evidence, not measured improvement.

## Assess supported behavior

Read the rubric after output capture. For each selected case, mark its gates Pass, Partial, Fail, or Not evaluated with an output excerpt or precise evidence pointer. Partial means some required behavior is present but incomplete; Not evaluated means evidence is insufficient, not success. Explain disagreements with the gate using the standard and fixture rather than silently changing expected results.

Look for meaningful diagnosis, appropriate evidence boundaries, preserved expertise/contracts, complete corrections, and concrete validation. Also check false positives: unnecessary simplification, invented research, unsupported runtime claims, and unauthorized actions. Keyword or heading presence alone is not a behavioral pass.

Use [the comparison record](references/comparison-record.md) to preserve outputs, provenance, gate results, regressions, and limits. Do not compute an aggregate that hides a critical failure or silently excludes failed/not-run cases. Keep this evaluation rubric separate from the product audit's 0–4 scores.

## Improve only what evidence supports

Identify a repeatable error or a specific instruction gap before revising the plugin. Rerun affected cases and relevant counterexamples after the change; retain unaffected accepted results with version provenance. Do not add a universal rule for every one-off response.

Report what ran, what was assessed, and whether improvements are supported under comparable conditions. Human discoverability, task success, and confidence remain unvalidated unless actual intended-user research supports them. Never claim a plugin-quality percentage or broader reliability from an unexecuted kit.

Referenced files: 15

View saved version →

---
name: connected-experience-design
description: Design or review how a user's task, identity, saved state, and service outcomes continue across relevant devices, platforms, products, or external systems. Use when system behavior changes user effort, trust, recovery, or a product promise; do not presume universal synchronization.
---
<!-- Copyright 2026 ArcanEdge AI. Licensed under Apache-2.0; preserve this notice when redistributing. Source: https://github.com/ArcanEdge-AI/intuitive-software-design -->

# Connected Experience Design

Use this skill when a task crosses surfaces or when backend, data, identity, or integration behavior materially changes what a person can do, understand, trust, or recover. Read the [authoritative standard](../intuitive-software-design/references/intuitive-software-design-standard.md), especially the system-backed experience contract. This skill applies that contract through UI, Flow, and Feel; it adds no fourth layer or score.

Do not load it for screen-only styling. Do not treat “connected” as a requirement to sync everything, make platform interfaces identical, or automate away a meaningful user decision.

## Establish the user's job and promise

Identify the intended person, task, realistic starting point, success condition, and evidence. Include the device, platform, account, collaborators, or external service only when they affect this job.

Record any relevant promise made by the product or website, such as work being saved, a task being resumable, or an action being completed elsewhere. Treat a marketing statement as a promise to investigate, not evidence that the capability works. Separate what is visible, documented, implemented, exercised, and still unknown.

## Choose the continuity the task actually needs

These capabilities are related but distinct. Assess only those relevant to the task:

- **Shared identity:** the person can establish which account, organization, or role is active.
- **Shared data:** the relevant domain object and its saved state are available on another surface.
- **Task handoff:** enough task-specific context is preserved for the person to resume useful work.
- **Platform capability:** each supported platform lets the person perform the needed action, using appropriate controls and conventions.
- **Connected action:** a service or another actor receives, processes, or completes a requested operation.

Do not infer shared data from shared sign-in, task handoff from data sync, edit capability from read access, or external completion from request delivery. If no cross-surface continuity is needed or authorized, say so and preserve the justified boundary.

## Trace the experience contract

Map the task through the relevant frontstage and system boundaries:

```text
User intent and product promise
  -> entry surface and active identity/authority
  -> task or domain-object identity
  -> user action and service/integration boundary
  -> actual current and durable state
  -> visible acknowledgment and next step
  -> continuation, correction, or recovery
```

Use a compact trace when more than one boundary matters:

| Task stage | User's question or intent | Visible cue or promise | System behavior and evidence | Actual state and acknowledgment | Continue or recover |
| --- | --- | --- | --- | --- | --- |

Check that object identity, ownership, state meaning, and authority remain coherent. An account can have multiple workspaces; a “Saved” label can refer to a local draft; a submitted request can still await processing. Expose technical boundaries only when they change a meaningful choice, risk, status, or outcome. Do not make people coordinate internal services or databases.

For website-to-product journeys, trace the consequential claim into the first product task that should fulfill it. Include sign-in, onboarding, setup, and the first saved or completed outcome only when they are on that path. Preserve a user's reasonable choice to evaluate, decline, or defer rather than treating conversion as the only success.

## Preserve useful context safely

Recommend the smallest amount of continuation that makes the task easier and more reliable. Identify which object, selection, progress, decision, or status must carry forward, and which interface details can appropriately change by platform.

Consider privacy and authority at each boundary: what information moves, who can access it, whether permissions change by device or role, and whether an action needs fresh consent or confirmation. Prefer task-relevant state over copying all local context. Do not expose sensitive information in notifications, handoff previews, or shared devices without evidence and authorization.

Select failure cases by consequence and evidence. When relevant, inspect offline work, slow or failed delivery, stale data, concurrent edits, duplicate activation, partial external completion, expired identity, and retry/reconciliation. For each selected case, establish what the person can see, whether their work is preserved, who owns the next action, and how they can safely continue. Do not impose an exhaustive matrix on a small task.

## Keep claims within evidence

Distinguish an attempted request, queued or pending work, durable saved state, confirmed external completion, and a usable continuation path. A toast, optimistic update, HTTP request, source path, or unit test alone may not prove the user-visible outcome. Use a suitable read-back, reload, authorized downstream view, state trace, or runtime observation when the claim requires it.

Source can show what code is intended to do; tests can show what a tested case did; runtime evidence can show what happened in that environment. None alone establishes that intended users can discover, understand, or trust the behavior. Label predictions and untested boundaries. Do not invent synchronization guarantees, latency targets, error rates, user research, or production incidence.

## Recommend and validate

Connect each recommendation as:

`observed promise or task barrier -> specific continuity gap -> user effort or risk -> smallest complete correction -> observable validation`

Include the visible status and a useful continuation or recovery path in the proposed interaction. Preserve effective platform differences, purposeful decisions, offline or local-only requirements, and existing privacy controls. Do not propose a new backend, shared account, sync layer, or integration unless the task evidence justifies that change.

Validate relevant behavior at each boundary: the same intended task/object, current identity and authorization, saved or external state, honest acknowledgment, and expected next action. Exercise failure/recovery paths only where scope and risk warrant. Separately validate user comprehension or discoverability with an uncoached task; implementation success is not usability proof.

## Return

State the task and evidence scope. Show the compact boundary trace when useful, then lead with the earliest consequential gap. Separate observations, inferences, and unknowns. Explain whether the need is shared identity, data, task handoff, platform capability, connected action, or none. Give the smallest supported correction and a concrete functional and, when relevant, human validation task. Do not assign numeric scores unless the main audit workflow requests them.

## Completion check

- The cross-surface capability follows a demonstrated user job or an explicit product promise.
- Identity, object/task state, action ownership, and actual completion are distinguished.
- Platform differences, authorization, privacy, and recovery are considered where relevant.
- No universal sync or architecture change is recommended without task-grounded evidence.
- Implementation claims and human usability claims remain within their evidence.

Referenced files: 1

View saved version →

---
name: decision-support-design
description: Design or review the information, comparisons, defaults, and consequences needed for meaningful user choices. Use for selection, comparison, approval, configuration, or purchase decisions when the UI may ask people to choose before they have enough information.
---
<!-- Copyright 2026 ArcanEdge AI. Licensed under Apache-2.0; preserve this notice when redistributing. Source: https://github.com/ArcanEdge-AI/intuitive-software-design -->

# Decision-Support Design

Make the decision understandable at the moment it is required. Read intended-user framing, Decision Density, progressive disclosure, error prevention, and guardrails in [the standard](../intuitive-software-design/references/intuitive-software-design-standard.md).

## Define the decision

Identify who chooses, their goal, relevant expertise, available options, consequence, reversibility, and information already known. Separate the person's decision from the business's desired conversion or preferred option. Include choosing later or declining only when legitimate for the task.

For each consequential decision, record:

| Choice | Information needed now | Material differences / tradeoffs | Default and justification | Consequence / correction | Evidence gaps |
| --- | --- | --- | --- | --- | --- |

Use task evidence to select comparison criteria. Do not invent preferences, eligibility, prices, guarantees, or a universally best option. A choice supported by domain judgment is not automatically UI friction.

## Evaluate support and timing

Check whether the interface:

- provides comparable units, scope, limitations, and relevant costs before commitment;
- shows enough context to choose without remembering another page;
- distinguishes factual differences from recommendation or marketing claims;
- explains why an option is unavailable and what can be done next;
- permits revisiting a reversible choice while preserving useful work;
- presents consequential defaults visibly with a task-grounded justification;
- defers information or choices only when they can safely wait.

Do not remove useful options to lower a decision count. Prefer grouping and meaningful comparison when complexity belongs to the job. Do not preselect spending, disclosure, notifications, or irreversible effects merely to shorten the flow. Preserve needed confirmations and disclose the scope of commitment.

Use [the walkthrough](../user-task-walkthrough/SKILL.md) to test the sequence and [UI language guidance](../intuitive-software-design/references/ui-language.md) when labels conceal differences or consequences.

## Example

Fixture: A plan selector lists Basic, Pro, and Premium with feature counts. The brief says the buyer needs team access and occasional exports. No current feature eligibility or pricing evidence is supplied.

Correction hypothesis: Compare the verified team-access/export limits and relevant commitments in the same place as the choice. Do not recommend Pro until those facts establish fit. A “Most popular” badge is not evidence that it serves this buyer.

Validation: Give likely buyers a realistic need and ask them to select an option and explain its consequences without revealing the intended plan. Separately verify that prices, restrictions, and selected configuration match the system behavior. Do not invent a completion or conversion target.

## Return

Lead with the decision that lacks necessary support. Connect evidence to the missing information, prediction/decision friction, smallest complete correction, and observable validation. Label proposed defaults and comparisons as hypotheses until supported. No numeric scoring unless requested through the main audit workflow; no purchase or configuration change without authorization.

Referenced files: 1

View saved version →

---
name: intuitive-software-design
description: Design, review, formally audit, score, or improve software screens, workflows, navigation, forms, dashboards, interactions, and product behavior using the Intuitive Software Design Standard. Use when the user asks whether software is intuitive, requests UI/Flow/Feel analysis, or wants the smallest evidence-grounded changes that reduce interaction friction. Do not use as a visual-style or trend critique.
---
<!-- Copyright 2026 ArcanEdge AI. Licensed under Apache-2.0; preserve this notice when redistributing. Source: https://github.com/ArcanEdge-AI/intuitive-software-design -->

# Intuitive Software Design

Apply the standard relative to the intended user. The objective is not to remove useful thought from the user's work; it is to keep the user from having to think about operating the software when they should be thinking about the job.

## Route the request

Classify the primary mode from the user's outcome, not from a keyword alone:

- `DESIGN`: shape something that does not yet exist or prevent intuition problems before implementation.
- `REVIEW`: diagnose an existing design or implementation and explain specific problems without requiring a complete formal scorecard.
- `AUDIT`: conduct a formal screen, workflow, or product evaluation with evidence, 0-4 scores, friction types, severity, and critical failures.
- `IMPROVE`: find the smallest complete changes that remove diagnosed friction while preserving what works.

Use one primary mode. Combine modes only when the user asks for both or when a small secondary step is necessary to complete the main outcome. State the mode briefly in formal work; do not burden a quick request with routing ceremony.

## Establish the evaluation frame

Before judging the experience, establish:

1. intended user and relevant experience or domain knowledge;
2. task and starting point;
3. success condition;
4. evidence available and important evidence missing.

Infer these from the request, repository, product documentation, user stories, interface, and domain context when reasonable. Ask only when a missing fact would materially change the result. Identify meaningful differences when more than one intended-user group is affected.

Never invent user behavior, research results, runtime behavior, hidden states, or scores. Mark a criterion `NE — Not Evaluated: Insufficient Evidence` when evidence cannot support it.

When the outcome depends on how a person discovers, chooses, or completes a task, use [User-Task Walkthrough](../user-task-walkthrough/SKILL.md) before diagnosing or proposing structure. Trace the relevant journey with user-accessible knowledge, visible cues, predicted consequences, and evidence-supported outcomes. Use a short trace for a small task; do not add a full journey report to a styling-only question. For a new design, treat the trace as proposed behavior rather than observed usability.

## Use the standard

The authoritative source is [the Intuitive Software Design Standard](references/intuitive-software-design-standard.md); it controls if this skill or a companion reference appears to conflict with it. Before answering, read the standard sections linked for your mode. They are this skill's required reading, and the rules summarized in this skill apply throughout:

- `DESIGN`: read the [design process](references/intuitive-software-design-standard.md#39-design-process), the [recovery and validation contract](references/intuitive-software-design-standard.md#recovery-and-validation-contract), and [references/examples.md](references/examples.md). Define the user's loop, states, decisions, feedback, recovery, and measurable acceptance before proposing structure.
- `REVIEW`: read the [review process](references/intuitive-software-design-standard.md#40-review-process) and the [friction taxonomy](references/intuitive-software-design-standard.md#part-iv--friction-taxonomy). Inspect the supplied evidence across UI, Flow, and Feel where observable. Use the friction taxonomy, Prediction Gap, Decision Density, Loop break, and critical-failure checks. Use examples only when comparison adds clarity.
- `AUDIT`: read the [audit process](references/intuitive-software-design-standard.md#38-audit-process) and [product-level assessment](references/intuitive-software-design-standard.md#34-product-level-assessment), read [references/scoring-reference.md](references/scoring-reference.md), and use [references/audit-template.md](references/audit-template.md). Do not calculate a screen, workflow, or product score from unevaluated criteria. Report each product dimension—UI Clarity, Flow Intuition, and Behavior Confidence—as `NE` unless its coverage is representative, and do not offer provisional or partial dimension percentages; a single screen's or workflow's percentage is not a product dimension. Behavior Confidence from one observed success path is `NE`, even when individual interaction criteria can be scored.
- `IMPROVE`: read the [improve process](references/intuitive-software-design-standard.md#41-improve-process), including its [recovery and validation contract](references/intuitive-software-design-standard.md#recovery-and-validation-contract). Trace each recommendation to evidence and an underlying friction source. Prefer a ranked smallest-complete-change plan. Redesign only when smaller changes cannot solve the diagnosed problem.
- For an AI-agent or code-review deliverable, use [references/ai-review-template.md](references/ai-review-template.md).

When a question is not settled by those sections and this skill, consult the rest of the standard, starting with its [foundation](references/intuitive-software-design-standard.md#part-i--foundation), [UI, Flow, and Feel model](references/intuitive-software-design-standard.md#6-ui-flow-and-feel), and [guardrails](references/intuitive-software-design-standard.md#part-vii--guardrails).

## Select focused guidance

Load only what changes the requested task; these are supporting capabilities, not a mandatory report set:

- If domain objects, relationships, lifecycle, or navigation structure are unclear, use [Product Mental Model](../product-mental-model/SKILL.md) before arranging screens.
- If selection, comparison, approval, or configuration lacks necessary context, use [Decision-Support Design](../decision-support-design/SKILL.md).
- If completion depends on another actor or external system, use [Multi-Role Workflow](../multi-role-workflow/SKILL.md).
- If the task crosses devices, platforms, products, or service boundaries—or a backend behavior materially changes effort, state, trust, or recovery—use [Connected Experience Design](../connected-experience-design/SKILL.md). Do not apply it to screen-only styling or presume that data should sync.
- If the user explicitly grants broad creative freedom to rethink an existing page or flow, use [Purpose-First Redesign](../purpose-first-redesign/SKILL.md) to separate what must work from layout choices. Keep `IMPROVE` diagnosis-driven by default; broad redesign is not implied by a request to fix friction.
- For locating information/actions, read [findability](references/findability.md).
- For action labels, status, instructions, and errors, read [UI language](references/ui-language.md).
- For first-product-use, occasional return, or repeated expert work, read [experience progression](references/experience-progression.md).
- When the user asks to test this plugin's agent-output quality, use [Behavioral Evaluation](../behavioral-evaluation/SKILL.md); it is separate from a product usability audit.

For proposed UI elements, explain the task question, decision, action, or confirmation they serve. Do not add controls or structure whose benefit cannot be tied to the user's job and supporting evidence.

## Operating rules

1. Separate observation from inference. Say what is visible or demonstrated, then explain the likely user consequence.
2. Evaluate `UI`, `Flow`, and `Feel` independently. A clear screen can belong to a poor workflow; attractive software can behave unpredictably.
3. Treat screenshots as evidence of visible UI, state cues, and predictive affordances only. They do not prove responsiveness, action results, transitions, error handling, recovery, keyboard operation, or broad Feel quality; mark those `NE`.
4. Locate the broken Intuitive Software Loop stage: Orient, Recognize, Predict, Act, Confirm, or Continue.
5. Name the friction precisely: Navigation, Interpretation, Decision, Interaction, Memory, Feedback, Recovery, or Process.
6. Keep severity separate from the 0-4 intuition score.
7. Report every Critical Failure separately; never average one away.
8. Treat accessibility as part of intuitive operation, while distinguishing confirmed defects from evidence that was not available.
9. Do not penalize appropriate professional density, domain terminology, or expert shortcuts. Judge whether the intended user can recognize structure, predict behavior, and work efficiently.
10. Do not equate minimal, modern, or aesthetically preferred interfaces with intuitive ones.
11. Recommend the smallest complete correction that resolves the underlying problem, includes necessary states and recovery, and preserves effective behavior.
12. When a promised result depends on a service, data store, or integration, distinguish the requested action, actual state, user-facing acknowledgment, and continuation or recovery. A dispatched request or optimistic update alone is not completion evidence.
13. Do not state a business rule—timing, price, eligibility, entitlement, or another policy outcome—that the evidence does not establish, even in proposed interface copy. Use a placeholder, and list each such rule for the owner to confirm.

## Recovery and validation contract

The standard's [recovery and validation contract](references/intuitive-software-design-standard.md#recovery-and-validation-contract) controls. Read it whenever you recommend or design a change; this summary keeps its requirements in view while you work and does not replace reading it. Apply the contract to every change you recommend or design, in every mode:

- For each consequential action you introduce or alter, define its pending, success, failure, and partial states, and prevent duplicate activation while work is pending.
- Show known constraints before the person commits; when an action is still rejected, explain the cause and the next step.
- On failure or interruption, keep the person's valid work and choices and give a clear way to continue or try again.
- Confirm the actual resulting state—what changed, and for which object—in a form the person can find again. State only outcomes the evidence establishes.
- Cover the branches the evidence names, such as eligibility windows, roles, or an object changed elsewhere before the action completed.
- Validate each important recommendation with a functional check of the resulting state and, when people must find, understand, or trust something, a check with intended users that states the goal without naming the control. Name the observable result that would show success. Support volume and other lagging signals can supplement that check but not replace it.

## Output calibration

For quick design help, answer directly with the intended user, key decision, proposed flow, essential states and recovery, important tradeoffs, and how to validate the design.

For reviews, lead with the most consequential diagnosis and cite specific evidence. Use concise findings unless the user requests a formal report. Do not use the audit template or assign numeric scores unless the user asks to score or the requested review is explicitly formal; omit the Score field and use qualitative evidence boundaries instead.

For audits, include scope and evidence confidence, separate critical failures, criterion scores with rationales, friction and Loop-break summaries, prioritized findings, and a smallest-complete-change plan. Use this finding shape when appropriate:

```text
Finding: [specific problem]
Area: UI | Flow | Feel | Cross-Cutting
Principle: [standard principle]
Friction Type: [taxonomy term]
Loop Break: Orient | Recognize | Predict | Act | Confirm | Continue
Evidence: [observable evidence]
User Impact: [effect on intended user and task]
Severity: Critical | High | Medium | Low
Score: [criterion and 0-4, or NE]
Recommendation: [smallest complete corrective change]
Expected Outcome: [observable improvement]
Validation: [test or evidence that would demonstrate improvement]
```

The full block, including `Score`, is for `AUDIT`, explicitly requested scoring, or an explicitly formal review. In an ordinary `REVIEW`, omit `Score` rather than manufacturing formality.

For improvements, connect each change as `evidence -> friction source -> correction with its states and recovery -> expected behavior -> validation`. Do not produce a screen redesign by default.

## Completion check

Before returning:

- the intended user, task, and success condition are explicit or reasonably inferred;
- claims stay within available evidence;
- UI, Flow, and Feel are distinguished where the evidence permits;
- scores use only the 0-4 behavioral rubrics and show `NE` where needed;
- critical failures are separate from averages;
- recommendations preserve what works and solve the entire diagnosed state or workflow gap;
- each recommended change meets the recovery and validation contract: failure and recovery states, a truthful confirmation, and validation with an observable result;
- no business rule the evidence does not establish is stated as fact, including in proposed copy;
- the answer is specific enough that a designer, developer, PM, QA reviewer, or AI agent can act on it.

Referenced files: 9

View saved version →

---
name: multi-role-workflow
description: Map product work across people, permissions, ownership, queues, and external handoffs. Use when a task requires submission, review, approval, processing, or collaboration and one person's completion depends on another actor or system.
---
<!-- Copyright 2026 ArcanEdge AI. Licensed under Apache-2.0; preserve this notice when redistributing. Source: https://github.com/ArcanEdge-AI/intuitive-software-design -->

# Multi-Role Workflow

Follow the whole job across actors, not only the current person's last screen. Read evidence discipline, context preservation, feedback, recovery, Critical Failures, and guardrails in [the standard](../intuitive-software-design/references/intuitive-software-design-standard.md).

## Define the actors and shared work

Establish the overall outcome and each actor's legitimate subtask. Identify the object being handed off, current owner, state, authority to act, needed information, and completion signals. Include relevant external systems or offline work from supplied evidence; do not invent email, spreadsheet, or operational dependencies.

| Stage / shared object | Actor and authority | Input and prerequisite | Action / transition | Next owner and visible acknowledgment | Failure / recovery | Evidence |
| --- | --- | --- | --- | --- | --- | --- |

Separate **permission**, **responsibility**, and **visibility**. A manager who can view a request may not own its next action. A successful submission does not prove delivery, review, approval, processing, or payment. Treat a service or integration as a system boundary with a real state transition, not automatically as another human role. When the same work must continue across devices or products, use [Connected Experience Design](../connected-experience-design/SKILL.md) for the relevant task and state continuity.

## Inspect consequential handoffs

For the task, check:

- whether the initiating actor can tell what was handed off, to whom, and what happens next;
- whether the receiver can discover and understand pending work with sufficient context;
- whether shared states distinguish submitted, received, in review, approved, rejected, processed, and failed when those meanings apply;
- whether amendments, returns, cancellation, and failed delivery preserve ownership and history;
- whether simultaneous edits, stale approvals, duplicate processing, or reassignment affect correctness;
- whether external completion is acknowledged and reconciliation/retry is clear when evidence supports such a boundary;
- whether a downstream service actually accepted or completed its stage, rather than merely receiving a request;
- whether each role sees appropriate information without exposing another role's private data.

Select checks by actual risk and scope. Do not add an enterprise queue or audit system to a simple workflow without a demonstrated need. An email notification alone does not prove the recipient can access or act on the object.

Use [user-task walkthrough](../user-task-walkthrough/SKILL.md) for each materially different actor journey and [product mental model](../product-mental-model/SKILL.md) if shared objects/states are unclear. Preserve role differences rather than averaging them into one usability judgment.

## Evidence and actions

Source and tests may support role rules but do not prove runtime authorization. A screenshot from one role cannot establish another role's experience. Exercise role transitions only in an authorized environment with appropriate accounts/fixtures. Do not send real notifications, approve requests, change permissions, impersonate roles, or process payments merely to complete a map. Mark untested handoffs and access behavior unknown.

## Example

Fixture: An employee's request shows “Complete” after submission. A manager queue screenshot lists that request as Pending. Finance behavior is not supplied.

Observed product states conflict in their apparent completion scope; actual confusion is an inference. A smaller correction may be “Submitted — awaiting manager review” for the employee while preserving the manager's actionable Pending state. Finance processing and access remain unknown. Do not claim end-to-end completion or invent a payment step.

Validation: In an authorized fixture, verify the handoff, receiver entry point, state agreement, relevant return path, and role-appropriate access. Separately ask each actor to explain what has happened and who acts next, without coaching them with the intended states.

## Return

Provide the actor/state map, consequential gaps, evidence-supported smallest corrections, selected failure/return paths, and validation per boundary. Identify critical misrouting, unauthorized disclosure, or irreversible effects separately. No unrequested scores or live workflow changes.

Referenced files: 1

View saved version →

---
name: product-mental-model
description: Map the objects, relationships, lifecycle states, and language an intended user works with before shaping product navigation or screen structure. Use when a UI exposes implementation modules, the product model is unclear, or a workflow needs information architecture grounded in domain work.
---
<!-- Copyright 2026 ArcanEdge AI. Licensed under Apache-2.0; preserve this notice when redistributing. Source: https://github.com/ArcanEdge-AI/intuitive-software-design -->

# Product Mental Model

Explain the product in the intended person's terms before deciding its screen structure. Read the foundation, mental-model alignment, and guardrails in [the standard](../intuitive-software-design/references/intuitive-software-design-standard.md). Do not replace domain contracts with invented simplifications.

## Build two models

Establish the intended user, job, starting knowledge, success, and evidence limits. Extract task-relevant vocabulary from the brief, domain documents, existing UI, source, and supplied research. User research can support a mental-model claim; UI and code alone show the product's model, not what people actually think. Label inferred user models as hypotheses.

Map only the objects and relationships needed for the task:

| User concept | Relationship / ownership | Lifecycle and meaningful transitions | Where the user recognizes it | Evidence / uncertainty |
| --- | --- | --- | --- | --- |

Distinguish an object's identity from its status, its parent from its owner, and an action from a navigation destination. For example, “Approved” may be a proposal state rather than a separate object. When a task crosses surfaces, establish whether the same domain object and lifecycle state are actually shared; do not infer that from a matching label or account. Do not infer cardinality, ownership, or legal meaning from names alone.

Separately inspect the implemented model: routes, entities, modules, permissions, and downstream effects. Where source is available, verify important relationships and transitions against current code/tests; otherwise mark them unknown. Compare the models for:

- concepts split across unrelated modules or multiple labels for the same thing;
- distinct concepts merged under a vague name;
- lifecycle transitions hidden as generic edits;
- dependencies users must understand but cannot see;
- relationships or terminology that differ materially across roles.

Implementation structure can be appropriate. Recommend a change only when a specific mismatch adds interpretation, navigation, memory, or process work.

## Propose a coherent structure

State what the product should help the person understand: which object they are working on, how it relates to the job, its state, available actions, and where work goes next. Propose grouping/navigation in those terms before components. Preserve identity, permissions, domain terminology, and consequential transitions.

Use [the task walkthrough](../user-task-walkthrough/SKILL.md) to check that the proposed structure supports the job from entry through continuation. Use [findability guidance](../intuitive-software-design/references/findability.md) when labels/grouping are the concern. A diagram or object table is optional when it clarifies relationships; it is not proof of usability.

## Example

Fixture: The brief describes “prepare a proposal for a client's project.” The UI has separate menus for Clients, Projects, Documents, and Pricing. Source connects proposal records to projects and recipients, but no research is supplied.

Hypothesis: A project-centered proposal entry point may match this job better than searching a global Documents module. Confirm existing access paths and role needs before recommending regrouping. Keep the global library if it supports cross-project work; do not force every role into one hierarchy.

Validation: Ask intended users where they would look to prepare or retrieve a proposal without naming the destination. Verify that any proposed grouping preserves authorized access and existing relationships. Do not claim a better mental model merely because a diagram is cleaner.

## Return

Give a compact user-concept map, supported implementation mismatches, smallest structural correction, preserved contracts, and concrete validation. Separate observed product structure from inferred user expectations. Avoid unrequested scores, invented research, schema changes, and implementation unless authorized.

Referenced files: 1

View saved version →

---
name: purpose-first-redesign
description: Redesign an existing software page or workflow when the user grants broad creative freedom and wants to discuss how it should work. Map the page's real purpose, users, data, actions, and downstream flows first; use GitNexus when available. Treat the current layout as evidence, not a constraint, and do not implement until the user asks.
---
<!-- Copyright 2026 ArcanEdge AI. Licensed under Apache-2.0; preserve this notice when redistributing. Source: https://github.com/ArcanEdge-AI/intuitive-software-design -->

# Purpose-First Redesign

Use this skill when an existing page may need more than incremental cleanup and the user wants to rethink how it should work before implementation.

The objective is to design around the user's job, not around the current component tree, database model, or visual layout.

## Required foundation

Before drafting, read the standard's [design process](../intuitive-software-design/references/intuitive-software-design-standard.md#39-design-process) and [recovery and validation contract](../intuitive-software-design/references/intuitive-software-design-standard.md#recovery-and-validation-contract); they are this workflow's required reading. Apply the contract to the proposed experience: the brief's states and validation items below summarize it, and [the Intuitive Software Design Standard](../intuitive-software-design/references/intuitive-software-design-standard.md) controls if they differ. Read [the examples](../intuitive-software-design/references/examples.md) when they help distinguish task structure from visual treatment, and consult the rest of the standard when a question is not settled here.

This is a `DESIGN` workflow informed by evidence from an existing product. Existing behavior is observable evidence; the proposed redesign remains a design hypothesis until validated with intended users.

## 1. Establish the redesign frame

Identify or reasonably infer:

- intended user and relevant domain experience;
- job the page should help them complete;
- starting point and successful end state;
- frequency, consequence, permissions, device, and time-pressure constraints;
- evidence available and important evidence still missing.

Ask only when a missing fact would materially change the product model. Do not start with components, cards, tables, or visual trends.

## 2. Map the page's real purpose

When GitNexus is available and the codebase is indexed, use it before proposing the redesign:

1. Read the repository context and check index freshness.
2. Query for the page, route, and the user job it supports.
3. Inspect the primary screen symbol and important callers/callees.
4. Read relevant process traces.
5. Verify implementation-relevant findings in current source and tests.

Trace this minimum product map:

```text
Route and entry points
  -> screen composition
  -> data sources and derived state
  -> visible and hidden actions
  -> downstream destinations and workflows
  -> role and permission gates
  -> loading, empty, failure, partial, and recovery states
```

Also inspect the rendered page when available. Exercise only safe, reversible interactions needed to understand behavior. A screenshot alone does not prove flow, responsiveness, keyboard operation, or recovery.

If GitNexus is unavailable, stale, or missing the repository, say so and use repository search, source inspection, tests, documentation, and runtime evidence instead. Never invent a process trace.

## 3. Separate purpose from inheritance

When domain objects, relationships, or lifecycle meaning are unclear, use [Product Mental Model](../product-mental-model/SKILL.md) to compare the user's inferred concepts with the implementation map. When work crosses actors or external systems, use [Multi-Role Workflow](../multi-role-workflow/SKILL.md) to identify ownership, shared states, and handoff boundaries before proposing structure.

Create two explicit inventories:

- **Must preserve:** domain contracts, consequential actions, permissions, data requirements, safe recovery, and proven useful behavior.
- **Free to rethink:** layout, grouping, navigation model, information hierarchy, interaction pattern, progressive disclosure, and visual composition.

Treat the current layout as evidence of what exists, not a requirement for what comes next. Do not preserve a table, card grid, dashboard, wizard, or side panel merely because it is already implemented.

## 4. Define the user's operating loop

Describe the intended sequence through:

```text
Orient -> Recognize -> Predict -> Act -> Confirm -> Continue
```

For the page, identify:

- the question the user is trying to answer on arrival;
- the first meaningful action;
- the information required before acting;
- the result and feedback after acting;
- the next useful destination or action;
- how context, filters, selection, and work survive return or interruption.

Inventory meaningful decisions and reduce Decision Density by deferring only choices that can safely wait.

Use [User-Task Walkthrough](../user-task-walkthrough/SKILL.md) to ground this loop in the intended person's knowledge and visible decision cues before proposing the product model. Trace the important existing journey and relevant continuation/recovery, then distinguish it from the proposed journey. Implementation knowledge from the purpose map must not silently become user knowledge.

When the page depends on saved work, identity, or a task continuing across devices, platforms, products, or services, use [Connected Experience Design](../connected-experience-design/SKILL.md) for those boundaries. Keep the redesign centered on the user's outcome; do not turn a product map into a request for universal sync or an architecture rewrite.

## 5. Propose the strongest product model

Recommend one coherent direction, not a pile of interchangeable mockups. Include alternatives only when they represent materially different workflows or tradeoffs.

Define:

- information architecture and primary hierarchy;
- direct actions and navigation behavior;
- beginner recognition and expert efficiency;
- default, loading, empty, pending, success, failure, partial, permission, and recovery states that actually apply;
- responsive and keyboard interaction contracts;
- what should remain visible versus progressively disclosed;
- measurable acceptance criteria.

Creative freedom does not waive evidence discipline. Novelty must reduce operating effort or improve task confidence. Do not state a business rule—timing, price, eligibility, entitlement, or another policy outcome—that the evidence does not establish, even in proposed copy; use a placeholder and list it for confirmation.

For consequential choices, use [Decision-Support Design](../decision-support-design/SKILL.md). Load [findability](../intuitive-software-design/references/findability.md), [UI language](../intuitive-software-design/references/ui-language.md), or [experience progression](../intuitive-software-design/references/experience-progression.md) only when those concerns affect this redesign.

## 6. Hold a design discussion before implementation

Return a discussion-ready brief containing:

1. **Purpose map** — what the page owns and where it leads.
2. **Primary diagnosis** — the earliest broken Intuitive Software Loop stage and main friction source.
3. **Recommended experience** — how the page should work from arrival through continuation.
4. **Screen structure** — a concise text wireframe or flow only when it clarifies relationships.
5. **Key decisions and tradeoffs** — choices that materially affect the product.
6. **States and recovery** — for each consequential action: the pending, success, failure, and partial states that apply; failure that keeps entered work and choices with a clear way to continue or try again; the branches the evidence names, such as eligibility windows; and a confirmation of the actual resulting state that states only what the evidence establishes.
7. **Validation** — a functional check of the resulting state and a check with intended users that states their goal without naming the control, plus the observable result that would show the redesign works. Do not invent targets or findings; lagging signals such as support volume only supplement these checks.
8. **Discussion prompt** — the smallest set of decisions the user should confirm, including every business rule the proposed experience depends on that the evidence does not establish.

Do not edit source, generate implementation files, or launch a build during this discovery/design pass unless the user explicitly asks for implementation in the same request.

## Quality gate

Before returning, verify that:

- the recommendation follows the user's job rather than technical architecture;
- GitNexus or the stated fallback evidence supports the purpose map;
- UI, Flow, and Feel are separated where evidence allows;
- observations, inferences, and design hypotheses are distinguishable;
- the current layout has not silently constrained the proposal;
- necessary risk controls and recovery remain intact;
- states, recovery, and validation meet the recovery and validation contract;
- proposed copy states no business rule the evidence does not establish;
- the result is specific enough to discuss and later implement.

Referenced files: 1

View saved version →

---
name: user-task-walkthrough
description: Walk through how an intended user would discover, decide, act, and verify completion across a product or website UI. Use when reviewing task usability, understanding a user journey, or shaping a workflow before proposing interface changes. Distinguish user-visible knowledge from agent implementation knowledge; do not use for visual styling alone.
---
<!-- Copyright 2026 ArcanEdge AI. Licensed under Apache-2.0; preserve this notice when redistributing. Source: https://github.com/ArcanEdge-AI/intuitive-software-design -->

# User-Task Walkthrough

Trace a person's goal through the interface, including the information they need to choose each action and recognize its outcome. A successful agent execution proves only that tested path worked; it does not establish human discoverability or usability.

Read the foundation, UI/Flow/Feel model, Intuitive Software Loop, and guardrails in [the authoritative standard](../intuitive-software-design/references/intuitive-software-design-standard.md). This skill operationalizes those principles; it adds no scoring system. Use [worked examples](references/worked-examples.md) when knowledge boundaries, website journeys, or incomplete evidence need clarification.

## Establish the task and knowledge boundary

Use the user's brief, product evidence, and relevant research to establish:

- **Person and goal:** role, relevant domain/product experience, trigger, and desired outcome. Describe task-relevant differences rather than inventing demographic personas.
- **Starting point:** where they arrive, prior choices, current object/account, and what they reasonably know at that moment.
- **Success:** the result they need and how they could recognize completion. Include continuation or later retrieval when part of the job.
- **Context:** frequency, stakes, permissions, device/input, and environmental constraints that materially affect this task.
- **Evidence:** what can be inspected, its scope and recency, assumptions, and missing information that could change the conclusion.

Infer cautiously from reliable context and ask only about material gaps. Preserve useful expertise: first use of this product does not imply ignorance of the domain.

Maintain a boundary between **user-accessible knowledge** and **agent-only knowledge**. Source code, API names, hidden routes, database fields, and test selectors can explain behavior but cannot establish that a person knows where to go. Update the user's knowledge only when the journey exposes information, or prior knowledge is justified. Do not jump to a hidden route to prove an entry point is discoverable.

## Trace the journey before recommending structure

Choose the consequential task or tasks within scope; do not inventory every control. Begin at the realistic entry point and follow the goal across pages, dialogs, and handoffs to recognizable completion. Do not equate reaching the final screen with achieving the result.

At each meaningful transition, examine:

1. **Intent and information:** What question is the person answering? What do they know, need to remember, or still need to learn?
2. **Visible clue and choice:** Which label, grouping, state, or convention suggests an action? Are competing choices distinguishable, and is the information needed to decide available?
3. **Prediction:** What consequence would that action reasonably suggest before activation? Treat this as an inference unless supported by actual user evidence.
4. **Action and result:** What behavior is demonstrated, specified, or proposed? Does it match the predicted consequence? Can pending, success, failure, and partial completion be distinguished?
5. **Continuation and recovery:** What signals completion or the next step? How can the person backtrack, correct a mistake, or resume with context intact?

If several actions appear plausible, record the ambiguity and trace a consequential alternative when useful. Do not choose the correct action solely because implementation inspection revealed it.

For a website, the job may be to understand the offer, establish trust, compare options, or decide whether to enquire. Evaluate whether the person's information needs are met; do not assume conversion is their only goal. When a claim promises less re-entry, saved progress, or use across devices or services, follow that promise into the first relevant product task and compare it with demonstrated behavior. For an application, trace the domain work and its effects on saved state and downstream work. For an unbuilt design, trace proposed cues and transitions and label them as design hypotheses.

## Choose relevant variants and evidence

Select variants by task consequence and available evidence: first encounter versus repeat use; invalid input or a changed decision; interruption and return; slow/failed/partial work; permission boundaries; supported mobile, keyboard, or assistive-technology use. If continuation crosses devices, platforms, or service boundaries, use [Connected Experience Design](../connected-experience-design/SKILL.md) to select the relevant identity, task-state, persistence, and recovery checks. Explain the coverage selected. Do not manufacture errors or force an exhaustive matrix onto a small request.

When runtime access is available, use the available browser or product tools to inspect visible states and authorized interactions. Record the tested role, route/state, action, outcome, and supporting screenshot, log, or artifact where useful. Review authority before saving, sending, purchasing, deleting, or changing permissions; a walkthrough is not permission to mutate real data. If an action cannot be exercised, preserve the prediction and mark its result unknown.

Without runtime access, use screenshots, source, specifications, or prototypes within their limits. Cite source paths for implemented behavior; do not call it observed runtime behavior. Screenshot-only evidence cannot prove transitions, persistence, recovery, or keyboard operation. Check save/reopen or downstream effects when relevant and authorized; a toast alone does not prove persistence.

Use supplied interviews, support reports, usability observations, or analytics to refine the task model. State which audience, task, and context each source covers. Analytics can show drop-off but may not explain its cause; support reports do not establish prevalence. Keep conflicting evidence visible rather than averaging away role differences. Do not obtain private research or install tools merely to fill evidence gaps.

## Return an actionable result

Use focused guidance when the trace reveals a deeper cause: [product mental model](../product-mental-model/SKILL.md) for unclear domain structure, [decision support](../decision-support-design/SKILL.md) for missing choice information, [multi-role workflow](../multi-role-workflow/SKILL.md) for human ownership handoffs, and [connected experience design](../connected-experience-design/SKILL.md) for relevant cross-surface or system-backed continuity. For local cue concerns, read [findability](../intuitive-software-design/references/findability.md), [UI language](../intuitive-software-design/references/ui-language.md), or [experience progression](../intuitive-software-design/references/experience-progression.md) as relevant. Do not expand a small walkthrough into all companion workflows.

Scale the output to the request. A short walkthrough can be a few paragraphs; use a trace table when several transitions need comparison:

| Step and intent | User knowledge and visible clue | Plausible action and expected consequence | Result and evidence | Continuation or gap |
| --- | --- | --- | --- | --- |

Identify **observations**, **inferences**, and **unknowns** throughout. Keep proposed behavior separate from existing behavior. Cite the artifact/state supporting consequential claims; do not invent quotes, success rates, timings, or human test results.

Lead with the earliest consequential task barrier. Connect findings as:

`specific evidence -> user knowledge/decision gap -> Loop break and friction -> smallest complete correction -> validation`

Preserve useful domain density, expert shortcuts, and risk controls. Include relevant pending, failure, recovery, and continuation in the correction. Identify critical failures separately. Use the main skill's audit rubric only when scoring is requested; omit numbers in ordinary walkthroughs.

End with coverage and remaining unknowns, plus a concrete validation task for the important change. Separate functional verification from human validation. Human task prompts should describe the goal without naming the correct control or giving the route; observe recognition, wrong turns, completion, and confidence without inventing targets. If human testing has not occurred, say the user consequence remains a hypothesis.

## Completion check

- The journey starts with a person's goal and realistic knowledge, rather than a component tree.
- The trace does not grant the person hidden implementation knowledge.
- Consequential choices have visible cues, needed information, predicted effects, and evidence boundaries.
- Completion, continuation, and selected recovery paths are covered or explicitly unknown.
- Recommendations follow evidence; agent success is not presented as human usability proof.

Referenced files: 2