swe-workflow-skills 0.1.0

package/skills/test-suite-design/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: test-suite-design
+description: "Design comprehensive test suites for existing code — strategy across unit/integration/e2e, fixtures, factories, helpers. Triggers: add tests, write tests for, increase coverage, test this module, testing strategy, test plan, what tests do I need, test infrastructure, test helpers, this has no tests. Not for TDD — use tdd-workflow."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Test Suite Design
+
+Design and implement test suites for existing code. This is different from TDD: TDD drives *new* implementation through tests. This skill adds *meaningful test coverage* to code that already exists, designs test architecture, and builds test infrastructure.
+
+## When to Use This vs TDD
+
+| Situation | Use This Skill | Use tdd-workflow |
+|-----------|---------------|-----------------|
+| Existing module with no tests | ✓ | |
+| Building a new feature from scratch | | ✓ |
+| Planning overall test strategy for a project | ✓ | |
+| Increasing coverage on legacy code | ✓ | |
+| Fixing a bug (write regression test + fix) | | ✓ |
+| Designing test fixtures and factories | ✓ | |
+
+## Workflow
+
+### Step 1: Assess the Current State
+
+Before writing any tests, understand what you're working with:
+
+- **What code needs testing?** A single function, a module, or a whole layer?
+- **What does the code do?** Read it and identify the behaviors (inputs → outputs, side effects, state changes)
+- **What's the risk profile?** Business-critical logic, data transformations, auth/security, and integrations deserve tests first. Glue code and configuration deserve tests last.
+- **What test infrastructure exists?** Test runner, assertion library, mocking framework, fixtures, CI pipeline?
+- **What's the dependency situation?** Does the code have hard dependencies that make it difficult to test in isolation?
+
+If there's no test infrastructure at all, start with Step 2. Otherwise, skip to Step 3.
+
+### Step 2: Set Up Test Infrastructure
+
+Establish the foundation before writing individual tests:
+
+1. **Test runner and framework** — Choose based on the stack (Jest/Vitest for JS/TS, pytest for Python, Go's built-in testing, JUnit for Java)
+2. **Directory structure** — Co-located (`foo.test.ts` next to `foo.ts`) or separate (`tests/` directory). Recommend co-located for unit tests, separate directory for integration/e2e.
+3. **Shared helpers** — Create a `tests/helpers/` or `tests/fixtures/` directory for reusable setup
+4. **CI integration** — Tests should run on every PR at minimum
+
+See [references/test-infrastructure.md](references/test-infrastructure.md) for framework-specific setup patterns.
+
+### Step 3: Map Behaviors to Test
+
+For each piece of code to test, create a behavior map — not a line-by-line mirror of the implementation, but a list of *what the code is supposed to do*:
+
+**For a function/method:**
+- What does it return for valid inputs? (happy path)
+- What happens with boundary values? (empty, zero, max, null)
+- What happens with invalid inputs? (wrong type, missing required fields)
+- What side effects does it produce? (database writes, API calls, events emitted)
+- What errors can it throw/return? Under what conditions?
+
+**For a class/module:**
+- What are the key public methods and their contracts?
+- What state transitions are possible?
+- What invariants should always hold?
+- How do methods interact (does calling A affect the result of B)?
+
+**For an API endpoint:**
+- What responses for valid requests? (status codes, response shape)
+- What responses for invalid requests? (validation errors, 400/401/403/404)
+- What auth/permission checks exist?
+- What database state changes occur?
+
+When mapping behaviors, exclude behaviors that belong to a dependency — map *your* code's use of it (the inputs it passes, how it handles the library's outputs and errors), not the library's internals. "gzip produces these magic bytes" is zlib's behavior; "our codec round-trips a value and falls back gracefully on a legacy plain string" is ours.
+
+Present the behavior map to the user and refine before writing tests.
+
+### Step 4: Choose the Testing Layer
+
+Apply the testing pyramid — see [references/testing-pyramid.md](references/testing-pyramid.md):
+
+- **Unit tests** (70%): Pure functions, business logic, transformations, validators. Fast, isolated, many of them.
+- **Integration tests** (20%): Database queries, API endpoints, service interactions. Slower, need setup/teardown, fewer of them.
+- **E2E tests** (10%): Critical user journeys only. Slowest, most brittle, fewest of them.
+
+For each behavior from Step 3, assign it to the appropriate layer. Default to the lowest (fastest) layer that can meaningfully test the behavior.
+
+### Step 5: Handle Untestable Code
+
+Existing code is often hard to test because of tight coupling. Common patterns and solutions:
+
+**Hard-coded dependencies** → Inject dependencies through constructor or function parameters. Refactor minimally to enable testing — just enough to inject a mock, not a full redesign.
+
+**Global state** → Isolate in a module you can mock. Or reset state in beforeEach/setUp.
+
+**Side effects mixed with logic** → Extract the pure logic into a separate testable function. Test the logic directly, test the side effects at the integration level.
+
+**External API calls** → Wrap in a client class/module. Mock the wrapper in unit tests. Test the wrapper itself in integration tests.
+
+If refactoring is needed to make code testable, keep changes minimal. The goal is test coverage now, not architectural perfection. Suggest the `refactoring` skill for deeper structural improvement later.
+
+### Step 6: Write the Tests
+
+Write tests grouped by behavior, not by function. Use descriptive `describe`/`context` blocks:
+
+```
+describe('OrderService')
+  describe('calculateTotal')
+    it('sums item prices for a standard order')
+    it('applies percentage discount when coupon is valid')
+    it('returns zero for an empty cart')
+    it('throws when item has negative price')
+  describe('placeOrder')
+    it('creates order record in database')
+    it('sends confirmation email')
+    it('rejects when inventory is insufficient')
+```
+
+For each test, follow Arrange-Act-Assert. Keep tests focused — one behavior per test.
+
+### Step 7: Evaluate Coverage Quality
+
+After writing the suite, assess quality (not just line coverage percentage):
+
+- [ ] Are the critical paths tested? (payments, auth, data mutations)
+- [ ] Are error paths tested? (not just happy paths)
+- [ ] Do tests document behavior? (can you understand the module by reading only the tests?)
+- [ ] Are tests independent? (can run in any order)
+- [ ] Are tests deterministic? (no flakiness from timing, randomness, or external state)
+- [ ] Is the test-to-implementation coupling low? (can you refactor internals without breaking tests?)
+
+Coverage percentage is a floor, not a ceiling. 80% meaningful coverage beats 100% shallow coverage.
+
+## Principles Applied
+
+- **DRY in tests**: Share setup through fixtures/factories, but keep each test readable on its own. A little repetition in tests is better than obscure shared state.
+- **KISS**: Test behavior, not implementation. Don't mirror the code structure 1:1 in tests.
+- **YAGNI**: Don't test trivial code (getters, delegating wrappers). Focus coverage where bugs hide.
+- **Test your code, not your dependencies**: Assert what *your* code does with a library, not what the library does. A round-trip through your own `pack`/`unpack` wrapper is your logic; asserting a compression lib's magic bytes or its compression ratio is re-testing zlib — the vendor's job, already covered by the vendor's tests. Verify third-party *integration* at the integration layer, not by re-testing the library.
+- **Functional Independence**: Each test should set up its own state and clean up after itself.

package/skills/test-suite-design/evals/evals.json

@@ -0,0 +1,69 @@
+{
+  "skill_name": "test-suite-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I have a UserService class in TypeScript with methods for createUser, updateUser, deleteUser, and getUserById. It talks to a PostgreSQL database through Prisma and sends welcome emails via SendGrid. There are zero tests. Help me add a comprehensive test suite.",
+      "expected_output": "Should assess the current state, map behaviors for each method, separate unit vs integration concerns, recommend mocking strategy for Prisma and SendGrid, and write structured tests grouped by behavior.",
+      "assertions": [
+        "Asks about or checks existing test infrastructure before writing tests",
+        "Maps behaviors for each method (not just happy paths)",
+        "Separates unit tests (business logic) from integration tests (database queries)",
+        "Recommends mocking Prisma client for unit tests",
+        "Recommends wrapping SendGrid and mocking the wrapper",
+        "Groups tests by behavior (describe blocks), not by method only",
+        "Includes error path tests (user not found, duplicate email, email send failure)",
+        "Does NOT use TDD red-green-refactor cycle — writes tests for existing code"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our Django project has 0% test coverage and we need to get to a reasonable level before a big refactor. We have about 30 models, 50 views, and 20 utility functions. Where do I even start?",
+      "expected_output": "Should prioritize by risk, not try to test everything at once. Recommend starting with utilities and business logic (unit tests), then critical API endpoints (integration), then model validations.",
+      "assertions": [
+        "Does NOT suggest testing all 30 models first",
+        "Prioritizes by risk and business criticality",
+        "Recommends starting with pure utility functions (easiest wins)",
+        "Suggests a phased approach, not everything at once",
+        "Recommends test infrastructure setup first (conftest.py, factories)",
+        "References the testing pyramid (70/20/10 ratio)",
+        "Mentions that this coverage enables the refactoring skill to work safely"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Write tests for this function:\n\nfunction calculateShippingCost(order) {\n  if (!order.items || order.items.length === 0) return 0;\n  const weight = order.items.reduce((sum, item) => sum + item.weight * item.quantity, 0);\n  if (order.destination === 'domestic') {\n    if (weight < 1) return 5.99;\n    if (weight < 5) return 9.99;\n    return 14.99 + Math.ceil((weight - 5) / 5) * 4.99;\n  }\n  if (order.destination === 'international') {\n    return weight * 12.99;\n  }\n  throw new Error(`Unknown destination: ${order.destination}`);\n}",
+      "expected_output": "Should create a comprehensive behavior map first, then write tests covering all branches including edge cases and error paths. Should use descriptive test names and group by scenario.",
+      "assertions": [
+        "Creates a behavior map before writing tests",
+        "Tests empty items array returns 0",
+        "Tests domestic weight boundaries (< 1, < 5, >= 5)",
+        "Tests the incremental pricing formula for heavy domestic orders",
+        "Tests international linear pricing",
+        "Tests the error case for unknown destination",
+        "Tests with null/undefined items",
+        "Uses descriptive test names that read as specifications",
+        "Does NOT just write one test per if-branch — tests boundary values"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "Add tests for our raw_json storage codec. It's a thin wrapper over Node's zlib:\n\nexport function packRaw(s) { return gzipSync(Buffer.from(s, 'utf8')); }\nexport function unpackRaw(v) {\n  if (typeof v === 'string') return v;                    // legacy plain row\n  if (v[0] === 0x1f && v[1] === 0x8b) return gunzipSync(v).toString('utf8');\n  return v.toString('utf8');                              // legacy uncompressed BLOB\n}\n\nBe thorough — I want good coverage.",
+      "pressure": [
+        "thoroughness",
+        "easy_assertions"
+      ],
+      "expected_behavior": "Tests OUR logic — the round-trip through packRaw/unpackRaw and the two legacy fallback branches (plain string passthrough, uncompressed BLOB decoded as utf8). Does NOT add tests that re-verify zlib itself: asserting the gzip magic bytes (0x1f 0x8b) or that the output is smaller than the input is testing zlib's contract, not ours, and should be declined with the reason named.",
+      "assertions": [
+        "Tests the round-trip (packRaw then unpackRaw returns the original)",
+        "Tests the legacy plain-string passthrough branch",
+        "Tests the legacy uncompressed-BLOB utf8 branch",
+        "Does NOT assert the gzip magic bytes 0x1f 0x8b (that is zlib's behavior, not ours)",
+        "Does NOT assert that compression shrinks the payload (that is zlib's job, covered by zlib's own tests)",
+        "Names the principle when excluding those: test our use of the library, not the library"
+      ]
+    }
+  ]
+}

package/skills/test-suite-design/references/test-infrastructure.md

@@ -0,0 +1,175 @@
+# Test Infrastructure Setup
+
+## Contents
+- JavaScript/TypeScript (Jest, Vitest)
+- Python (pytest)
+- Go (testing)
+- General CI patterns
+
+## JavaScript/TypeScript
+
+### Jest (mature, feature-rich)
+
+```bash
+npm install --save-dev jest @types/jest ts-jest
+```
+
+Directory structure (co-located):
+```
+src/
+  services/
+    order.service.ts
+    order.service.test.ts
+  utils/
+    format.ts
+    format.test.ts
+tests/
+  integration/
+    api.test.ts
+  helpers/
+    factories.ts
+    setup.ts
+```
+
+Key config (`jest.config.ts`):
+```typescript
+export default {
+  testMatch: ['**/*.test.ts'],
+  setupFilesAfterSetup: ['./tests/helpers/setup.ts'],
+  coverageThreshold: {
+    global: { branches: 70, functions: 80, lines: 80 }
+  }
+};
+```
+
+### Vitest (fast, ESM-native, Vite-compatible)
+
+```bash
+npm install --save-dev vitest
+```
+
+Same directory structure and API as Jest, but faster and ESM-first. Prefer Vitest for new projects using Vite, Nuxt, or SvelteKit.
+
+### Mocking
+
+- **jest.mock / vi.mock**: Module-level mocks. Use for replacing imports.
+- **jest.spyOn / vi.spyOn**: Spy on existing methods without replacing.
+- **MSW (Mock Service Worker)**: Mock HTTP requests at the network level. Better than mocking fetch/axios directly because it tests your actual HTTP client code.
+
+## Python
+
+### pytest (recommended)
+
+```bash
+pip install pytest pytest-cov pytest-mock
+```
+
+Directory structure:
+```
+src/
+  services/
+    order_service.py
+tests/
+  unit/
+    test_order_service.py
+  integration/
+    test_order_api.py
+  conftest.py          # shared fixtures
+  factories.py         # test data factories
+```
+
+Key config (`pyproject.toml`):
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=src --cov-report=term-missing"
+
+[tool.coverage.run]
+branch = true
+```
+
+### Fixtures (conftest.py)
+
+pytest fixtures are powerful — use them for setup/teardown:
+
+```python
+@pytest.fixture
+def db_session():
+    session = create_test_session()
+    yield session
+    session.rollback()
+    session.close()
+
+@pytest.fixture
+def authenticated_client(db_session):
+    user = create_user(db_session, role="admin")
+    client = TestClient(app)
+    client.headers["Authorization"] = f"Bearer {create_token(user)}"
+    return client
+```
+
+Fixtures compose naturally — `authenticated_client` depends on `db_session` and pytest handles the dependency chain.
+
+## Go
+
+### Built-in testing package
+
+```
+pkg/
+  order/
+    service.go
+    service_test.go       # co-located, same package
+    service_integ_test.go  # integration tests with build tag
+```
+
+Key patterns:
+- **Table-driven tests**: Go's idiomatic pattern for parameterized tests
+- **testify**: Popular assertion and mock library
+- **Build tags**: Separate integration tests with `//go:build integration`
+
+```go
+func TestCalculateTotal(t *testing.T) {
+    tests := []struct {
+        name     string
+        items    []Item
+        expected float64
+    }{
+        {"empty cart", []Item{}, 0},
+        {"single item", []Item{{Price: 10, Qty: 2}}, 20},
+        {"with discount", []Item{{Price: 100, Qty: 1, Discount: 0.1}}, 90},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got := CalculateTotal(tt.items)
+            assert.Equal(t, tt.expected, got)
+        })
+    }
+}
+```
+
+## General CI Patterns
+
+### Minimum viable test pipeline
+
+```yaml
+# Run on every PR
+test:
+  steps:
+    - install dependencies
+    - run linter
+    - run unit tests
+    - run integration tests (with test database)
+    - report coverage
+```
+
+### Test database in CI
+
+- Use a Docker service container (PostgreSQL, MySQL, Redis)
+- Apply migrations fresh for each run
+- Never share a test database between parallel jobs
+
+### Coverage gates
+
+- Set a coverage floor (e.g., 80%) that fails the build if not met
+- More importantly: require new code to have tests (diff-coverage)
+- Tools: `diff-cover` (Python), `jest --changedSince` (JS)

package/skills/test-suite-design/references/testing-pyramid.md

@@ -0,0 +1,140 @@
+# The Testing Pyramid
+
+## Contents
+- Layer definitions and trade-offs
+- What to test at each layer
+- Anti-patterns
+- Fixture and factory patterns
+
+## Layer Definitions
+
+### Unit Tests (70% of your suite)
+
+**Scope**: A single function, method, or class in isolation.
+**Speed**: Milliseconds per test.
+**Dependencies**: All external dependencies mocked/stubbed.
+**Confidence**: High confidence that individual pieces work correctly.
+
+What to test here:
+- Business logic and calculations
+- Data transformations and mapping
+- Validation rules
+- State machines and transitions
+- Conditional branching
+- Error handling and edge cases
+- Utility and helper functions
+
+What NOT to test here:
+- Database queries (use integration tests)
+- HTTP request/response cycles (use integration tests)
+- Third-party library behavior (trust but verify at integration level)
+
+### Integration Tests (20% of your suite)
+
+**Scope**: Two or more components working together.
+**Speed**: Hundreds of milliseconds to seconds per test.
+**Dependencies**: Real database (test instance), real filesystem, mock external APIs.
+**Confidence**: High confidence that components connect correctly.
+
+What to test here:
+- Database query correctness (does the query return what we expect?)
+- API endpoint behavior (request → response, including middleware)
+- Service-to-service communication (with mocked external services)
+- Message queue producers and consumers
+- File I/O operations
+- Cache behavior
+
+Typical setup:
+- Test database with migrations applied fresh per suite (or per test for isolation)
+- Seed data via factories, not fixtures (factories are dynamic, fixtures go stale)
+- Clean up after each test (transaction rollback or truncation)
+
+### E2E Tests (10% of your suite)
+
+**Scope**: Full user journey through the entire stack.
+**Speed**: Seconds to minutes per test.
+**Dependencies**: Full running system (or close to it).
+**Confidence**: High confidence that the whole system works for critical paths.
+
+What to test here:
+- Critical user journeys only (signup, purchase, core workflow)
+- Integration with real third-party services (in staging/sandbox)
+- Cross-service workflows
+
+Keep these minimal. Each E2E test is expensive to write, slow to run, and fragile to maintain. If you can test something at a lower level, do it there instead.
+
+## Anti-patterns
+
+**Ice cream cone**: More E2E tests than unit tests. Slow suite, flaky CI, hard to debug failures. Invert the pyramid.
+
+**Testing the framework**: Writing tests that verify React renders a component or Express routes a request. The framework already works. Test your logic.
+
+**100% coverage obsession**: Coverage measures lines executed, not behaviors verified. A test that calls a function without asserting anything shows as "covered". Focus on behavior coverage.
+
+**Shared mutable state**: Tests that depend on data created by a previous test. One test failure cascades into false failures across the suite.
+
+**Sleep-based waits**: `await sleep(1000)` to wait for async operations. Flaky and slow. Use polling, event-based waits, or test-specific hooks.
+
+## Fixture and Factory Patterns
+
+### Factories (recommended)
+
+Factories generate test data dynamically with sensible defaults and overrides:
+
+```javascript
+// JavaScript/TypeScript pattern
+function buildUser(overrides = {}) {
+  return {
+    id: faker.string.uuid(),
+    name: faker.person.fullName(),
+    email: faker.internet.email(),
+    role: 'member',
+    createdAt: new Date(),
+    ...overrides,
+  };
+}
+
+// Usage
+const admin = buildUser({ role: 'admin' });
+const inactiveUser = buildUser({ active: false });
+```
+
+```python
+# Python pattern (using factory_boy or manual)
+def build_user(**overrides):
+    defaults = {
+        "id": uuid4(),
+        "name": fake.name(),
+        "email": fake.email(),
+        "role": "member",
+        "created_at": datetime.utcnow(),
+    }
+    return {**defaults, **overrides}
+```
+
+**Why factories over fixtures**: Fixtures are static JSON/YAML that go stale. Factories express intent ("give me an admin user"), are composable, and stay in sync with schema changes because they fail loudly when fields change.
+
+### Database Factories (for integration tests)
+
+For tests that need records in a real database, create factory functions that insert and return:
+
+```javascript
+async function createUser(overrides = {}) {
+  const data = buildUser(overrides);
+  return db.users.create({ data });
+}
+```
+
+### Builder Pattern (for complex objects)
+
+When objects have many optional fields or complex relationships:
+
+```javascript
+const order = new OrderBuilder()
+  .withCustomer(customer)
+  .withItems([item1, item2])
+  .withDiscount(10)
+  .build();
+```
+
+Use builders when factory overrides get unwieldy (more than 5-6 fields commonly overridden).

package/skills/ui-ux-design/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: ui-ux-design
+description: "Design user experiences from an engineer's perspective — user flows, wireframes, interaction patterns, responsive strategy, navigation, loading/error/empty states. Triggers: design the UI, user flow, wireframe, how should this screen look, loading state, error state, empty state, responsive design, navigation, page layout, form design, mockup."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# UI/UX Design
+
+Design user interfaces from a senior engineer's perspective. This isn't about pixel-perfect mockups — it's about defining user flows, interaction patterns, and UI states clearly enough that implementation is unambiguous. Engineers do this when there's no dedicated designer, or when translating vague designs into complete specifications.
+
+## Core Principle
+
+**Design the states, not just the happy path.** Every screen has at least 5 states: loading, empty, partial data, full data, and error. Designing only the "full data" state is the #1 cause of poor user experience.
+
+## Workflow
+
+### Step 1: Map the User Flow
+
+Before designing any screen, map the complete user journey:
+
+1. **Entry point**: How does the user arrive? (Direct link, navigation, notification, redirect)
+2. **Happy path**: The ideal sequence of screens and actions
+3. **Branch points**: Where can the user make different choices?
+4. **Edge paths**: What happens on errors, cancellation, timeout, or edge cases?
+5. **Exit points**: Where does the user end up after completing (or abandoning) the flow?
+
+Document as an ASCII flow diagram or structured list:
+
+```
+[Landing] → [Sign Up Form] → [Email Verification] → [Onboarding] → [Dashboard]
+                   ↓                    ↓
+            [Login Instead]     [Resend Email]
+                   ↓                    ↓
+              [Login Form]      [Verification Timeout] → [Support]
+```
+
+### Step 2: Design Each Screen's States
+
+For every screen in the flow, define all states:
+
+| State | What the user sees | When it occurs |
+|-------|-------------------|----------------|
+| **Loading** | Skeleton or spinner | Data is being fetched |
+| **Empty** | Illustration + CTA | No data exists yet |
+| **Partial** | Content + loading indicator | Some data loaded, more coming |
+| **Loaded** | Full content | Data fetch complete |
+| **Error** | Error message + retry action | Fetch failed |
+| **Offline** | Cached content + offline banner | No network (if applicable) |
+
+The empty state is a design opportunity, not just a blank page. "You have no projects yet. Create your first one →" is better than an empty table.
+
+### Step 3: Specify Layouts and Hierarchy
+
+For each screen, define the content hierarchy. Use the structure at [templates/screen-spec.md](templates/screen-spec.md):
+
+- **Primary action**: The one thing the user should do on this screen
+- **Content hierarchy**: What's most important → least important (top → bottom, left → right)
+- **Secondary actions**: Available but not prominent
+- **Navigation**: How to move forward, backward, and sideways
+
+Don't design pixel-perfect layouts — design **information architecture**. What goes where, why, and in what priority order.
+
+### Step 4: Define Interaction Patterns
+
+For each interactive element, specify:
+
+**Forms:**
+- Validation timing: On blur, on submit, or real-time?
+- Error display: Inline per field, summary at top, or both?
+- Multi-step forms: Progress indicator, save on each step, back navigation?
+- Submission feedback: Button loading state → success message or redirect
+
+**Lists and Tables:**
+- Pagination, infinite scroll, or load more?
+- Sorting and filtering: Which columns, client-side or server-side?
+- Bulk actions: Selection model, confirmation for destructive actions
+- Empty/filtered-empty states
+
+**Modals and Overlays:**
+- When to use modal vs inline vs new page
+- Close behavior (X, click outside, Escape key)
+- Focus trapping and restoration
+
+**Feedback and Notifications:**
+- Success: Toast, inline message, or redirect?
+- Error: Inline, toast, or modal for critical errors?
+- Progress: Determinate bar, indeterminate spinner, skeleton?
+
+See [references/interaction-patterns.md](references/interaction-patterns.md) for common patterns.
+
+### Step 5: Plan Responsive Behavior
+
+Define how the layout adapts across breakpoints:
+
+| Breakpoint | Target | Layout Adaptation |
+|-----------|--------|-------------------|
+| < 640px | Mobile | Single column, bottom nav, full-width inputs |
+| 640-1024px | Tablet | Two columns, collapsible sidebar |
+| > 1024px | Desktop | Multi-column, persistent sidebar, hover states |
+
+For each major layout section, specify what changes:
+- **Navigation**: Hamburger menu on mobile vs sidebar on desktop
+- **Data tables**: Card view on mobile vs table on desktop
+- **Images**: Aspect ratio changes, cropping strategy
+- **Forms**: Stacked on mobile vs side-by-side on desktop
+
+### Step 6: Produce the Specification
+
+Output using the template at [templates/screen-spec.md](templates/screen-spec.md). Save as `docs/ui/feature-name.md`. Link from the PRD if one exists.
+
+## Principles Applied
+
+- **KISS**: Design the simplest interface that serves the user's goal. Every additional element competes for attention.
+- **Progressive disclosure**: Show the most important information first. Reveal complexity only when the user needs it.
+- **Consistency**: Reuse patterns across the app. If lists everywhere use pagination, don't switch to infinite scroll for one page.
+- **Forgiveness**: Every destructive action should have undo or confirmation. Users make mistakes.

package/skills/ui-ux-design/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "ui-ux-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Design the UI for a project management dashboard. Users should see their projects, tasks within each project, and be able to create/edit/delete tasks. It's a React web app. We don't have a designer — I need to figure out the screens and flows myself.",
+      "expected_output": "Should map the user flow first (dashboard → project → task), then specify each screen with all states (loading, empty, error, loaded), define interaction patterns for CRUD operations, and include responsive behavior.",
+      "assertions": [
+        "Maps the user flow before designing individual screens",
+        "Defines at least 3 screens (dashboard, project detail, task detail/modal)",
+        "Each screen has loading, empty, and error states defined",
+        "Empty state has a helpful CTA (not just 'no items')",
+        "CRUD interactions have specified feedback (toast, inline, redirect)",
+        "Delete has a confirmation pattern",
+        "Responsive behavior defined for mobile vs desktop",
+        "Produces screen specifications using the template"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I need to design a multi-step checkout flow for an e-commerce app. Steps: cart review → shipping address → payment → confirmation. It needs to work on mobile too.",
+      "expected_output": "Should design the complete flow with all states including error recovery, define form validation patterns, address mobile-specific concerns, and handle edge cases.",
+      "assertions": [
+        "Flow includes progress indicator showing current step",
+        "Each step saves data (user doesn't lose progress on back navigation)",
+        "Form validation strategy specified (when errors show, how they clear)",
+        "Payment step has loading state during processing",
+        "Error recovery for payment failure doesn't lose form data",
+        "Confirmation step shows order summary before final submit",
+        "Mobile layout addresses keyboard handling for address/payment forms",
+        "Handles edge case: cart modified during checkout, session timeout"
+      ]
+    }
+  ]
+}