pragmatic-design

Reviews and creates design artifacts from the consumer's perspective using operationalization checks.

Updated Nov 21, 2025
One-click install
npx skills add https://github.com/alatyshau/duet --skill pragmatic-design-alatyshau
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: pragmatic-design
Source: https://github.com/alatyshau/duet/tree/main/packages/skills/tools/pragmatic-design
Command: npx skills add https://github.com/alatyshau/duet --skill pragmatic-design-alatyshau

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Design artifacts often describe the system instead of guiding the consumer, mixing implementation details with purpose and proposing solutions that cannot actually be executed. This Skill reframes design work around who consumes the artifact and what they need to accomplish. ## Core Features & Use Cases - Create mode: Set the frame before designing — identify the consumer, their task, and success criteria, then design through that lens. - Review mode: Run a finished artifact through consumer criteria to find where you wrote "for yourself" instead of "for the consumer". - Two-check validation: Verify solutions are operationalizable (the user can actually act on them) and available (the proposed UI or tool actually exists). - Use Case: When writing an API response description for an AI agent, replace architectural explanations like "peer to other root contexts" with actionable guidance like "default folder for paths, starting points for navigation". ## Quick Start Review this design document from the consumer's perspective and flag anything written for the implementer instead of the user.

Frequently Asked Questions about pragmatic-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review a design document from the user's perspective?

Identify who consumes the artifact and what task they need to accomplish, then check every sentence against that goal. Flag anything that describes the system's architecture instead of telling the consumer what to do with it.

What is consumer-first design in technical documentation?

Consumer-first design means every field, sentence, or endpoint either helps the reader accomplish their task or is removed as noise. It contrasts with implementation-first writing that documents how the system works internally.

How do I know if a proposed solution is actionable?

Walk the user's path end to end: where they see the problem, how they understand what to do, and what tool they use to fix it. If any answer is "somehow", the solution is not operationalizable yet.

When should I remove technical details from documentation?

Remove implementation details only after classifying each element as load-bearing purpose or decorative detail. Statements capturing the artifact's purpose, like "multi-root workspace covering everything", should be kept even when simplifying.

What are the limitations of this design review approach?

The skill is a draft of raw observations and cases, not a finalized methodology. It provides principles and real cases rather than rigid checklists, so applying it requires judgment about each artifact's consumer and context.