ship-workflow-clarity
Skill2 starsChanged 3 months agoMITView on GitHub
Route and audit workflow clarity, human-obviousness, comprehension, attention, ease of use/ease-of-use, accessibility visibility, trust/proof/governance clarity, and ease-of-use risks in UI/product experiences. Use when auditing apps, pages, flows, dashboards, forms, onboarding, prototypes, games, creative or expert tools, AI copilots, governed or high-risk workflows, mobile/desktop/native/web surfaces, screenshots, DOM/browser traces, design artifacts, repositories, changed UI/workflow changes, or agent-assisted/wave-based audits using Playwright or Computer Use for user confusion, unclear next actions, cognitive burden, workflow friction, where users get lost, what is not obvious, requests to make this easier to understand, or harmful simplification.
In this repository4 other files it gives its agents.
- llms.txtllms.txt
- ship-deep-reviewSkill
- ship-product-workflowsSkill
- ship-readiness-orchestratorSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 10 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Use this skill as a router plus compact audit protocol.
- Distinctive: line 25
Use a provisional route from the prompt, then re-route after cartography if evidence shows broader scope, higher mutation risk, …
- Distinctive: line 29
Start with discovery and workflow cartography before judging UI quality.
- Distinctive: line 31
Use runtime/user-visible evidence when available.
- Distinctive: line 32
Never claim screenshot-only certainty about workflow behavior, accessibility, or absence.
- Distinctive: line 33
If evidence is thin, produce bounded findings and evidence requests rather than pretending workflow truth is confirmed.
- Distinctive: line 35
Do not click mutating, irreversible, paid, privacy-sensitive, permissioned, publishing, or destructive actions unless the user's …
- Distinctive: line 37
Never provide naked scores, decimal grades, or generic advice such as "make it cleaner" without workflow evidence and user consequence.
- Distinctive: line 43
Run the router pass: classify process route, audit mode, evidence path, and risk gate.
- Very specific: line 52
If the user does not choose, run a scoped audit_high_risk plus audit_top_tasks pass and name exclusions.
- Distinctive: line 70
Do not absorb every reference by default.
- Very specific: line 82
Use or adapt the templates in templates/ when the audit needs a reusable artifact:
- Very specific: line 108
When operating as a Shipworthy lane, also return coverage limitations and newly discovered candidates.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Shipworthy Workflow Clarity
Core Promise
Route and audit whether a human can tell where they are, what object or state they are acting on, what matters now, what action is legitimate next, what will happen, what will not happen, and how to recover. Treat obviousness as workflow comprehension, not prettiness.
Router Contract
Use this skill as a router plus compact audit protocol. The goal is to choose the lightest process that can produce a trustworthy evidence-backed audit, then escalate only when scope, risk, runtime evidence, agents, or validation demands it.
Route on four separate axes:
- Process route:
tiny,standard,major, orvalidation. - Audit mode:
audit_all,audit_selected,audit_top_tasks,audit_high_risk, oraudit_changed_only. - Evidence path: screenshot/static, repo/diff, browser/runtime, native/desktop, design artifact, transcript/CLI, user research, or mixed.
- Risk gate: none/low/medium/high mutation risk.
Process route controls how much machinery to load. Audit mode controls which workflows to inspect. Evidence path controls tools and artifacts. Risk gate controls what not to click.
Use a provisional route from the prompt, then re-route after cartography if evidence shows broader scope, higher mutation risk, tool/runtime needs, or skill-validation needs.
Operating Rules
- Start with discovery and workflow cartography before judging UI quality.
- Stay program-agnostic: adapt to web, native, mobile, desktop, game, creative, expert, CLI-like, AI, governed, and prototype surfaces.
- Use runtime/user-visible evidence when available; use static artifacts only with bounded confidence.
- Never claim screenshot-only certainty about workflow behavior, accessibility, or absence.
- If evidence is thin, produce bounded findings and evidence requests rather than pretending workflow truth is confirmed.
- For major, broad, high-stakes, or multi-surface audits, use parallel agents and/or waves when the runtime and user instructions permit it; keep small audits single-agent unless delegation would materially improve evidence.
- Do not click mutating, irreversible, paid, privacy-sensitive, permissioned, publishing, or destructive actions unless the user's authorization covers the exact action and a verified non-production reset/sandbox contract exists. A disposable fixture alone does not grant authority.
- Report findings first. Put scores last, omit them by default, and use only coarse labels when requested.
- Never provide naked scores, decimal grades, or generic advice such as "make it cleaner" without workflow evidence and user consequence.
- Preserve necessary complexity, proof, governance, expert controls, accessibility paths, recovery paths, and productive friction.
- Label assumptions about users, roles, goals, frequency, and business intent.
Audit Workflow
- Run the router pass: classify process route, audit mode, evidence path, and risk gate. Load only the references specified below. Name the route briefly when useful.
- Discover the artifact under review: app type, launch path, target surface, available credentials, seed data, device constraints, safe-test boundaries, user-stated goals, and requested audit mode.
- Map workflow cartography before auditing: surfaces, actors, states, actions, hidden paths, variants, and mutation risks. Under a full Shipworthy run, consume the orchestrator's source-backed candidate inventories and canonical coverage manifest; return newly observed raw candidates and exact proposed mappings, never a competing frontier or a frontier-derived census. Re-route once if cartography changes the process route, audit mode, evidence path, or risk gate.
- Select the audit mode:
audit_all: audit the whole discoverable workflow surface.audit_selected: audit user-selected workflows or surfaces.audit_top_tasks: audit likely high-frequency or user-critical tasks.audit_high_risk: audit irreversible, permissioned, money, privacy, security, publishing, AI-assisted, trust-heavy, or compliance-heavy workflows.audit_changed_only: audit changed routes, components, screens, or flows from a diff. If the user does not choose, run a scopedaudit_high_riskplusaudit_top_taskspass and name exclusions.
- Decide whether to use a single-agent pass, parallel agents, or staged waves. For major or runtime-heavy audits, follow the major-route guidance below before dispatching agents or tools.
- Collect evidence appropriate to the artifact: screenshots, recordings, DOM or UI tree, accessibility tree, focus path, route/surface map, workflow trace, labels/actions inventory, logs, network/API traces where safe, code references, product docs, or user-test data. Code and docs support claims; they do not replace what users can see and do.
- Route each workflow to archetypes after cartography, not before. Use a primary archetype plus overlays, such as dashboard, CRUD, form, AI copilot, governance, expert tool, mobile, native desktop, creative/game, or CLI-like interface.
- Analyze orientation, state clarity, attention, next action, consequence clarity, workflow continuity, recovery, accessibility, trust/proof, responsive survival, and expert control.
- Stress-test every recommendation before reporting it: ask what the fix could hide, weaken, remove, or make worse for another role, state, device, accessibility path, or governance boundary.
- Report findings first with evidence, severity, confidence, role/state/device, user consequence, smallest useful fix, verification step, and regression risk.
Visual or layout findings remain needs-proof without the exact viewport,
target state, reproduction steps, retained screenshot/geometry receipt, and a
separate source mechanism. A fresh disconfirmation blocks a false mechanism
from upgrading the symptom. Passed/Keep records state what to preserve and
the regression guard, never a corrective instruction; target intent determines
whether missing deployment evidence is a fixture scope limit or a production
release gate.
Reference Routing
Do not absorb every reference by default. Route first, then load by dependency order.
tiny: one screenshot, copy snippet, small component, or known narrow workflow. Use the workflow steps above; readreferences/evidence-severity-and-assumptions.mdbefore findings or scores,references/diagnostic-rubric-and-stress-tests.mdbefore recommendations, andreferences/accessibility-and-copy-pass.mdwhen interaction, copy, focus, or responsive behavior is in scope.standard: one product area, normal multi-state workflow, or unclear-but-bounded audit. Read in this order:references/workflow-cartography.md,references/audit-mode-playbook.md,references/evidence-severity-and-assumptions.md,references/accessibility-and-copy-pass.mdunless truly irrelevant,references/archetype-overlays.mdafter workflow types are known, thenreferences/diagnostic-rubric-and-stress-tests.md.major: broad, high-stakes, multi-surface, agent-assisted, wave-based, browser-runtime-heavy, native-app-heavy, Playwright, Computer Use, Codex macOS, or Claude macOS audit. The coordinator reads this core pack before dispatching agents or tools:references/workflow-cartography.md,references/audit-mode-playbook.md,references/evidence-severity-and-assumptions.md,references/agent-and-tool-orchestration.md, andreferences/diagnostic-rubric-and-stress-tests.md.majorlane add-ons: loadreferences/accessibility-and-copy-pass.mdfor accessibility/copy lanes,references/archetype-overlays.mdafter workflow types are known, and templates only when producing reusable artifacts.validation: readreferences/pressure-testing.md; also read the route-specific references needed for the scenario being tested.
Escalate route when the first map reveals hidden states, shared components, multiple actors, medium/high mutation risk, inaccessible paths, browser/native runtime dependence, contradictory evidence, requested agents/waves, or high-stakes trust/governance consequences. Downshift when the request is narrower than it first appeared and heavier evidence would not change the answer.
Templates
Use or adapt the templates in templates/ when the audit needs a reusable artifact:
workflow-map.json: structured cartography inventory.audit-report.md: findings-first report skeleton.finding-ledger.md: issue ledger for deeper reviews.evidence-inventory.md: artifact and confidence register.assumption-ledger.md: role, task, goal, and product assumption tracking.workflow-trace.md: step-by-step path evidence.
Output Contract
Lead with findings unless the user explicitly asks for only a map or only a plan. Use this order for a full audit:
- Top findings or no confirmed findings
- Scope and evidence used
- Workflow cartography inventory
- Process route, audit mode, evidence path, risk gate, and exclusions
- Assumption ledger
- Agent/tool orchestration used, if any
- Archetype routing
- Evidence inventory
- Short summary, only after findings
- Open questions
- Non-findings or bounded hypotheses
- Recommended next pass
When operating as a Shipworthy lane, also return coverage limitations and newly discovered candidates. Do not derive readiness. The orchestrator alone reports audit lifecycle, coverage finality/qualification, and release disposition; a completed audit may still be not_ready.
For every standalone user-facing final response with unfinished workflows, roles, states, variants, proof, or blocked/omitted checks, add an exhaustive Remaining Work section directly in the inline chat final response; HTML and artifact links cannot substitute for it. Include stable IDs/keys, status, reason/blocker, next action/proof, and resume condition. End with: “Would you like me to continue through every remaining safe, authorized path and proof item?” followed by “Would you like me to make that continuation a persistent goal so it resumes from the saved checkpoint until the frontier is exhausted?” Put no user-facing prose after those questions. If goal mode is active or unavailable, use the corresponding active-goal or goal-equivalent wording from $ship-readiness-orchestrator. When lane-dispatched, return the unresolved register to the orchestrator rather than asking the user.
For each finding, include:
[Severity][Confidence] Workflow / role-state-device: issue title
Evidence: artifact path, trace step, UI tree node, code/doc support, or user-test note
Observation: what was seen
Why it matters: likely user or task consequence
Recommendation bucket: Simplify | Preserve | Add Friction | Do Not Change
Fix: smallest concrete change
Stress test: what the fix could break
Verify: exact check to confirm improvementDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

