Update to Spreadsheet Human UX

{
  "description": "Design or review human-facing spreadsheets, Google Sheets, workbooks, dashboards, trackers, models, simulators, and decision tools so they are easy to understand, operate, resume, and trust. Use when spreadsheet usability, navigation, input safety, visual hierarchy, accessibility, cognitive load, or decision clarity materially affects whether people can use the artifact correctly; pair with technical spreadsheet/formula skills rather than replacing them.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 332
    },
    {
      "relative_path": "assets/composer-icon.png",
      "size_in_bytes": 647613
    },
    {
      "relative_path": "assets/logo.png",
      "size_in_bytes": 647613
    },
    {
      "relative_path": "references/design-patterns.md",
      "size_in_bytes": 4211
    },
    {
      "relative_path": "references/financial-decision-model.md",
      "size_in_bytes": 2681
    },
    {
      "relative_path": "references/provenance.md",
      "size_in_bytes": 1928
    }
  ],
  "name": "spreadsheet-human-ux",
  "skill_md_contents": "---\nname: spreadsheet-human-ux\ndescription: Design or review human-facing spreadsheets, Google Sheets, workbooks, dashboards, trackers, models, simulators, and decision tools so they are easy to understand, operate, resume, and trust. Use when spreadsheet usability, navigation, input safety, visual hierarchy, accessibility, cognitive load, or decision clarity materially affects whether people can use the artifact correctly; pair with technical spreadsheet/formula skills rather than replacing them.\n---\n\n# Spreadsheet Human UX\n\nDesign the **human interaction layer** of a spreadsheet. Preserve analytical correctness, formulas, provenance, and auditability; do not trade them away for visual polish.\n\nThis skill complements spreadsheet execution, data-quality, financial-modeling, and domain-verification skills. It does not own those concerns.\n\n## 1. Preflight the human task\n\nBefore changing tabs, cells, or styling, identify:\n\n- **User:** who operates or reads the workbook, and what expertise can be assumed?\n- **Task:** what recurring job or decision must they complete?\n- **Context:** desktop/mobile, shared/solo, time-pressured/exploratory?\n- **Frequency:** one-off, frequent, periodic, or resumed after long gaps?\n- **Risk:** what happens if a value is misunderstood or the wrong cell is edited?\n- **Complexity:** which inputs, scenarios, calculations, outputs, and evidence are materially necessary?\n- **Success:** what should the user be able to answer or do without help?\n\nTreat the user model as runtime context. Never hard-code a named person or Project unless that identity is the actual purpose of the artifact.\n\n## 2. Decide whether a UX layer is warranted\n\nUse this skill when human interaction matters. Do not polish a raw evidence table, archival registry, or machine-oriented dataset merely because it is a spreadsheet.\n\nWhen a structured backend table must also support frequent human use, preserve the data layer and add a user-facing surface instead of weakening the underlying structure.\n\n## 3. Design the common path first\n\nOptimize the first view and normal workflow for the 80% task. Keep advanced assumptions, calculations, evidence, and audit detail accessible through progressive disclosure.\n\nPrefer the smallest visible information architecture that works. A decision-facing workbook often benefits from a path such as:\n\n**START / DASHBOARD → INPUTS → SCENARIOS / DECISION → DETAIL / MODEL → EVIDENCE / SOURCES**\n\nThis is a pattern, not a mandatory template. Read `references/design-patterns.md` when designing or materially restructuring the workbook.\n\n## 4. Make inputs safe and obvious\n\nFor every material editable input, make visible:\n\n- human-readable label;\n- current value;\n- unit/format;\n- status or source when material;\n- short clarification where ambiguity is likely.\n\nPrefer prevention over warning-after-the-fact: controlled dropdowns, validation bounds, protected formula regions, safe defaults, explicit required fields, and checks for impossible combinations.\n\nGroup inputs by **user intent**, not by formula dependency. Reduce typing when options are known, while preserving spreadsheet flexibility where exploration is valuable.\n\n## 5. Make outputs interpretable\n\nA key result should carry enough context to stand on its own: value, unit, relevant period, active scenario/baseline, and a concise interpretation when useful.\n\nExpose the variables that can change the decision. Prefer sensitivities, ranges, or breakevens to false precision when uncertainty is material.\n\nCharts are optional. Use them only when a relationship, trend, sensitivity, or composition is faster to understand visually than as a number or table.\n\n## 6. Reduce cognitive load without hiding logic\n\nUse recognition over recall: visible labels, units, edit conventions, scenario indicators, legends, and nearby explanations.\n\nUse consistent visual semantics for the same kinds of things across the workbook. Favor spacing, alignment, hierarchy, and restrained emphasis over decorative color or dense borders.\n\nNever encode meaning only by color. Keep material calculations and evidence reachable so simplification does not become opacity.\n\n## 7. Preserve agency and resumability\n\nDo not turn a spreadsheet into a rigid pseudo-application. Users should be able to inspect assumptions, understand material calculation logic, safely change scenario inputs, see consequences, and reach evidence.\n\nDesign so the workbook remains understandable after time away. Make the current scenario/period, edit conventions, primary result, warnings, and next action easy to recover.\n\n## 8. Design for errors, accessibility, and device constraints\n\nWarnings should explain:\n1. what is wrong;\n2. why it matters;\n3. what to change or check.\n\nConsider missing inputs, stale data, invalid dates/rates, formula errors, contradictory assumptions, impossible values, and scenario-not-selected states.\n\nMaintain readable typography, descriptive headers, logical table structure, adequate contrast, text labels in addition to color, minimal unnecessary merged cells, and meaningful number formats.\n\nFor mobile/tablet use, keep the critical path narrow and vertically understandable; do not place essential controls far to the right or depend on hover/comments for core instructions.\n\n## 9. Apply optional domain profiles only when relevant\n\nFor financial, investment, fiscal, or other decision models, read `references/financial-decision-model.md`.\n\nDomain profiles add specialized UX concerns; they do not override the core method or stronger domain evidence requirements.\n\n## 10. Validate with realistic human tests\n\nBefore delivery or after a material redesign, run the tests that fit the workbook:\n\n- **5-second:** is the purpose and principal result immediately identifiable?\n- **Common-task:** can the main task be completed without hunting through technical tabs?\n- **Recognition:** are editable cells, units, scenario, and status obvious without memory?\n- **Error:** do blank, invalid, extreme, or contradictory inputs fail safely and explain recovery?\n- **Resume:** would the workbook still make sense after weeks away?\n- **Small-screen:** can the core result and controls still be used on a narrow viewport when relevant?\n- **Accessibility:** does meaning survive without color and remain logically readable?\n- **Traceability:** can a material result be followed to assumptions/evidence without reverse-engineering the whole workbook?\n\nUse realistic data. Do not declare UX complete from an empty template alone.\n\n## Delivery gate\n\nPASS only when the primary task is obvious, the common path is short, inputs and outputs are unmistakable, major errors are prevented or recoverable, uncertainty is visible, decision-relevant detail remains accessible, the first view is calm and scannable, accessibility/device risks were considered, and formulas/data remain technically correct and traceable.\n\n## Boundaries\n\nDo not:\n\n- hide uncertainty or provenance for aesthetic simplicity;\n- expose every technical calculation on the default surface;\n- over-engineer a simple one-off sheet;\n- make color the only status signal;\n- assume a dashboard is useful merely because the workbook has many tabs;\n- make the grid rigid when spreadsheet flexibility is valuable;\n- optimize visual polish at the expense of correctness or auditability;\n- duplicate technical spreadsheet execution rules already owned by another skill.\n\nFor the external basis and adaptation provenance, read `references/provenance.md`.\n"
}