Update to Intuitive Software Design

{
  "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 239
    }
  ],
  "skill_md_contents": "---\nname: product-mental-model\ndescription: 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.\n---\n<!-- Copyright 2026 ArcanEdge AI. Licensed under Apache-2.0; preserve this notice when redistributing. Source: https://github.com/ArcanEdge-AI/intuitive-software-design -->\n\n# Product Mental Model\n\nExplain 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.\n\n## Build two models\n\nEstablish 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.\n\nMap only the objects and relationships needed for the task:\n\n| User concept | Relationship / ownership | Lifecycle and meaningful transitions | Where the user recognizes it | Evidence / uncertainty |\n| --- | --- | --- | --- | --- |\n\nDistinguish 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.\n\nSeparately 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:\n\n- concepts split across unrelated modules or multiple labels for the same thing;\n- distinct concepts merged under a vague name;\n- lifecycle transitions hidden as generic edits;\n- dependencies users must understand but cannot see;\n- relationships or terminology that differ materially across roles.\n\nImplementation structure can be appropriate. Recommend a change only when a specific mismatch adds interpretation, navigation, memory, or process work.\n\n## Propose a coherent structure\n\nState 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.\n\nUse [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.\n\n## Example\n\nFixture: 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.\n\nHypothesis: 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.\n\nValidation: 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.\n\n## Return\n\nGive 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.\n"
}