Skill instructions
behavioral-evaluation4.31 KB
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
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 15 — file references are metadata, not package contents.
connected-experience-design7.67 KB
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 rathe
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
decision-support-design3.7 KB
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 — file references are metadata, not package contents.
intuitive-software-design13.9 KB
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
For a user journey map, interactive task walkthrough, or comparison of changes in an existing map, hand off to [User-Task Walkthrough](../user-task-walkthrough/SKILL.md#map-the-journey) for the HTML and its source record. Apply the modes below when the request also calls for design work, diagnosis, or scoring.
For questions about which paths people take and what happens afterwards, use [Journey Analytics](../journey-analytics/SKILL.md) with supplied behavior evidence.
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
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 9 — file references are metadata, not package contents.
journey-analytics5.78 KB
View saved version →
---
name: journey-analytics
description: Analyze supplied behavioral events or aggregates for next actions, completion, waiting time, rework, and recovery in a software journey. Measure by cohort and make eligibility, follow-up windows, and evidence gaps explicit.
---
<!-- Copyright 2026 ArcanEdge AI. Licensed under Apache-2.0; preserve this notice when redistributing. Source: https://github.com/ArcanEdge-AI/intuitive-software-design -->
# Journey Analytics
Use the project's authorized event exports, aggregate reports, or supplied research. Link measurements to the task or decision they describe. For a whole journey, use [User-Task Walkthrough](../user-task-walkthrough/SKILL.md) to map the goal and [Multi-Role Workflow](../multi-role-workflow/SKILL.md) when one person's action hands work to another.
Use the `fixture` basis for supplied synthetic event records or measured aggregates. Test setup, scripted choices, expected assertions, and timeouts describe what a test exercises. Cite them in the route evidence. If the inputs contain only those definitions or product rules, leave decision counts and outcome metrics absent and state what data could support them.
## Define the decision population
1. Identify the product version or environment, step, available choices, and cohort. Use role, starting state, or experience where those differences affect eligibility or interpretation.
2. Define an eligible opportunity. For a visible choice, use people or cases shown the choice while it was available. Account for people who could perform only one option, test traffic, duplicated events, and missing exposure coverage.
3. Choose a capture period, counting unit, and follow-up window appropriate to the task. A repeated click can be one decision opportunity. For work that passes across people, join only on the authorized work item or run and check what each role actually received.
## Measure next actions
- For an event export, map the eligibility and action events to the project step and choices. Count the first recorded mapped action per eligible opportunity within the follow-up window. Inspect timestamps, duplicates, and which late or incomplete opportunities have a full window. Use a local query or script for aggregation so the counts are reproducible.
- For aggregates, confirm that the numerator and denominator describe the same unit, cohort, period, and window. Require mutually exclusive counts for ranking first choices. Preserve known zeros and show unmapped opportunities without assigning them a cause. Missing telemetry, waiting on another role, and confirmed abandonment have different evidence.
- Report counts with the eligible denominator, period, source, and any meaningful capture or sampling limitations. Rank recorded choices within their cohort. Treat low counts, ties, selection bias, and product changes as limits on predictions. Event sequences show what was recorded. Use research with an appropriate task and population to explain possible reasons or suggest hypotheses worth testing.
- Preserve rare high-consequence paths and supported routes with sparse data. A frequently taken route may still signal friction, a requirement, or a default.
## Measure journey outcomes
Define the task's successful outcome from the workflow evidence. For an event export, use a local query or script to group events by the authorized work item or task opportunity, sort them by time, and deduplicate repeated records. Follow each eligible item from a known entry through its own window. For aggregates, verify the source describes the same eligibility, event definitions, and follow-up before reusing a result. Keep independent samples separate even when their cohort labels match.
- **Completion.** Count distinct eligible items with evidence of the specified outcome within the window. Classify other cases from a known terminal result or verified follow-up coverage. Use the result the person came for as the completion event.
- **Waiting time.** Def
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
multi-role-workflow8.68 KB
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.
Build the role inventory before tracing the steps. For each assignment or decision, record the product's role label, the work it owns, and its scope. Inspect both the shared record and any parts assigned independently. When the interface supports different assignment modes, check the controls and saved assignments for each in-scope mode. Use a walkthrough or test fixture to establish the route it exercises, then check the other modes in the current implementation or specification.
Keep separately assigned roles distinct even when they share a workspace, permissions, or a person. A record owner and a specialist responsible for an assigned part have different scopes. Use the role's label from the evidence and state when its assignment applies. Group labels only when the evidence shows their responsibilities are interchangeable throughout the scoped workflow. Keep a supported role in the inventory when its entry point or actions are unknown, and state the gap.
When a broad role in a summary or permission check differs from the role named by the assignment controls, saved assignment, or relevant test, trace those sources together before naming the actor. Use the assigned role's label for the route shown. Keep broader eligibility in the authority description and conflicting or older labels in the evidence note. Combine labels only if the sources establish them as aliases for the same assignment mode and responsibility. Record both whole-record and part-level assignments when the evidence supports both. The test account's job title or permission alone cannot establish who owns the work.
Before mapping the actions that follow an assignment, reconcile the assignment controls and saved work with the role inventory. Give each evidenced assignee a `people` entry and link it from the assigning step's [`assignments` field](../user-task-walkthrough/references/journey-map.md#write-the-record). Keep a role with a known assignment in that list even when the sources leave its next action open.
| 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
At every change of owner, identify the work being transferred, the condition that sends it,
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
product-mental-model4.41 KB
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
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
purpose-first-redesign9.14 KB
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:** doma
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
user-task-walkthrough12.7 KB
View saved version →
---
name: user-task-walkthrough
description: Trace how people discover, decide, act, and verify completion in software. Use for task usability reviews, end-to-end user journey maps, and workflow design. For a full map, trace meaningful choices, recovery, and changes of ownership. Generate interactive HTML when requested. Distinguish user-visible knowledge from implementation evidence.
---
<!-- 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 be
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.