Specify

---
name: specify
description: >
  Bridges design and engineering by producing detailed specs, organized
  handoff packages, asset inventories, and cross-functional documentation.
  Part of the Intent design strategy system. Trigger when: writing design
  specs, preparing engineering handoffs, documenting for development,
  creating design reviews, writing test plans, building copy matrices,
  addressing edge cases, aligning stakeholders, packaging designs
  "for engineering," or saying "write the spec," "prepare the handoff,"
  "document this," or "what do we need for design review?"
version: 1.6.0
user-invocable: true
---

# Specify — Bridge Design to Engineering

## Overview

This skill transforms design work into actionable, implementation-ready documentation. It produces structured specs, asset packages, test plans, and stakeholder presentations that ensure design intent survives to production. Use this when design needs to move into engineering, when cross-functional clarity is required, or when you must document decisions in a way that prevents rework.

---

## Skill family

Specify works alongside the full Intent skill system:

- **`/strategize`**: Their briefs and hypotheses provide the "why" behind everything you specify. Every spec should trace back to a strategic intent — why this feature exists, what hypothesis it tests, what user need it serves.
- **`/investigate`**: Their research findings ground your use cases in evidence. Real user quotes, observed behaviors, and validated pain points make specs persuasive and accurate, not hypothetical.
- **`/blueprint`**: Their system architecture constrains and informs your specs. Service dependencies, data flows, and technical constraints shape what's possible and what needs engineering discussion.
- **`/journey`**: Their flows are what you're specifying — screen sequences, interaction transitions, state changes. Journey designs the experience; specify documents it for implementation.
- **`/organize`**: Their information architecture informs your navigation specs. Taxonomy, hierarchy, and labeling decisions from organize become the structural backbone of your screen specs.
- **`/articulate`**: Their copy work feeds directly into your copy matrices. Voice, tone, and content strategy decisions become specific strings in your spec.
- **`/fortify`**: Their edge case analysis becomes part of your spec. Error states, failure modes, boundary conditions, and recovery patterns — all documented screen by screen.
- **`/include`**: Their accessibility requirements go into every screen spec. ARIA labels, keyboard navigation, color contrast, screen reader behavior — inclusion is not an appendix, it's woven into every screen.
- **`/evaluate`**: Their assessment identifies gaps in your specs. Heuristic violations, usability issues, and anti-pattern flags become items to resolve before handoff.
- **`/measure`**: Their success metrics define your test plan criteria. Every feature spec should include what success looks like, how to measure it, and what to instrument.
- **`/philosopher`**: A cross-cutting cognitive mode for when specification reveals deeper problems. Invoke when: edge cases keep multiplying, something about the design feels fragile under real conditions, the "pending questions" section keeps growing, or the user says "sit with this", "brainstorm", or "what could go wrong that nobody has imagined?" The philosopher helps think through failure scenarios nobody has considered and whether the spec is documenting the right thing.

---

## Core capabilities

### 1. Detailed design specifications

Write comprehensive, screen-by-screen (or state-by-state) specifications that document:
- Visual design with specific measurements, colors, typography, spacing
- Interaction logic: what triggers what, in what order, with what conditions
- Copy: exact text, variants for different contexts/markets/edge cases
- States: default, hover, active, error, loading, empty, success — all documented visually and logically
- Constraints: device sizes, performance requirements, accessibility needs

Output should be a living spec document (HTML or markdown) that engineers can reference during implementation without guessing.

### 2. Organized engineering handoff packages

Structure deliverables so engineering knows exactly what to build and why:
- Clear ownership: who decided what and when
- Problem context: what user need or business problem does this solve
- Design approach: constraints considered, alternatives rejected and why
- Use cases: specific, not generic — real user scenarios that expose edge cases
- Assets: all files organized, named, versioned, with usage notes
- Test criteria: success metrics and audience-specific test plans

### 3. Copy and variant matrices

Document all copy variations in one place:
- Primary copy vs. secondary copy vs. microcopy (labels, hints, errors, empty states)
- Market variants: tone shifts, cultural considerations, regulatory language
- Edge cases: character limits, long strings, very short strings, numeric edge cases
- A/B test variations: explicit copy changes being tested, with success criteria

### 4. Interactive HTML specification documentation

When appropriate, produce interactive HTML specs that:
- Show designs inline with explanatory text
- Link related screens and decisions
- Include collapsible reference sections (component specs, copy matrices, test plans)
- Are self-contained and viewable in any browser without external dependencies

### 5. Use case and edge case documentation

Write out specific, not generic use cases:
- "First-time user creating an account" vs. "User logs in"
- "Network timeout during payment" vs. "Error state"
- "User has 200+ items in cart" vs. "User has items in cart"
- Document how the design behaves in each case, what copy appears, what happens next

### 6. Stakeholder presentations

Structure presentations that align cross-functional teams:
- Problem statement (from `/strategize`)
- Design approach and constraints considered
- Key decisions and what was intentionally NOT done
- Test plan: what we're measuring and why (from `/measure`)
- Open questions: what we still need to resolve
- Timeline and dependencies

### 7. Test plans with success criteria

Write test plans that pair observations with decision-makers:
- Who needs to see this work (PM, engineering lead, CEO?)
- What success looks like: specific, measurable outcomes (connected to `/measure` GSM chains)
- What we're learning and why we're learning it
- How results feed back into design iteration

---

## Output format template

Follow this structure for comprehensive handoffs:

```
## Ownership & Context
- Owner: [Name, role]
- Created: [Date]
- Status: [Draft/Ready for Engineering/In Implementation]
- Design document version: [v0.1, etc.]

## Problem & User Need
[1-2 paragraphs: what problem does this solve, for whom, why now]

## Design Approach
- Constraints considered: [device, performance, accessibility, brand, etc.]
- Design strategy: [how we approached the problem]
- What we did NOT do (and why): [alternatives considered and rejected]

## UX Questions Answered
[List specific design questions this spec resolves, e.g.:
- How does the user know this action succeeded?
- What happens if the API returns no results?
- How do we handle very long titles?]

## Ethical Review
[Before handoff, check the design against Intent's anti-pattern catalog:]
- Patterns reviewed: [list specific interaction patterns checked]
- Potential concerns: [any patterns that could be perceived as manipulative]
- Design intent documentation: [for each concern, document the intent behind the decision and why it serves user interest]
- Dark pattern clearance: [explicit statement that the design was reviewed and does not employ deceptive, coercive, or manipulative patterns]

## Measurement
[Connected to /measure's success criteria:]
- Primary success metric: [from GSM mapping]
- Counter-metrics: [what must NOT get worse]
- Instrumentation needs: [what events/data engineering needs to capture]
- Learning plan: [when to check metrics post-launch — day 1, week 1, month 1]

## Design Specification

### Screen [Name/ID]
**Intent:** [Why does this screen exist? What user need does it serve? What happens if we remove it?]

**Behavior:** [What does the user see and what can they do?]

**Layout & Styling:**
- [Specific measurements, spacing, colors, fonts]
- [Visual hierarchy and grid placement]

**Copy:**
- Headline: "[Exact copy]"
- Description: "[Exact copy]"
- Button label: "[Exact copy]"
- Error state: "[Exact copy]"
- Empty state: "[Exact copy]"

**Interaction Logic:**
- On load: [what happens]
- On user action [X]: [expected outcome]
- On error [Y]: [fallback behavior and messaging]

**Accessibility:**
- ARIA labels: [if needed]
- Keyboard navigation: [if needed]
- Color contrast: [ratios if non-standard]

**States:** [Visual and copy documentation for default, hover, active, error, loading, empty states]

[Repeat for each screen/state]

## Use Cases & Variants

### Use Case 1: [Specific scenario]
[Describe the user journey, what they see at each step, what copy appears, what happens on success/failure]

### Use Case 2: [Specific scenario]
[Repeat as needed; be specific, not generic]

## Copy Matrix

| Element | Primary | Edge Case 1 | Edge Case 2 | Market Variant (DE) | A/B Test Variant |
|---------|---------|-------------|-------------|-------------------|-----------------|
| Headline | "[Copy]" | "[Copy]" | ... | ... | ... |
| [Repeat for each copy element] |

## Test Plan

### Audience 1: [PM / Engineering / End User]
**What we're testing:** [Specific behavior]
**Success looks like:** [Measurable outcome, connected to Measurement section]
**How we measure it:** [method/tool]

### Audience 2: [Different audience]
[Repeat as needed]

## Pending Questions

### Design Questions
- [Question 1: impacts design decision]
- [Question 2: impacts design decision]

### Engineering Questions
- [Question 1: impacts implementation approach]
- [Question 2: impacts implementation approach]

## Assets & Deliverables

**Design files:**
- [Figma file name and link]
- [Specific artboards/pages to reference]

**Handoff package contents:**
- Design spec (this document)
- Design files (Figma link)
- Copy matrix (separate or embedded)
- Test plan (separate or embedded)
- [Any other assets]

**File naming & organization:**
- [How files are named and organized in assets/]
- [Version control approach if applicable]

## Appendix

[Reference material: component specs referenced, design system tokens, brand guidelines excerpts, accessibility standards applied, etc.]
```

---

## Quality checklist

Before marking a handoff as complete, verify:

- [ ] Every screen has a documented intent — why it exists and what user need it serves (no real estate tours)
- [ ] All screens and states are visually documented
- [ ] All copy is written out (no placeholders like "TBD")
- [ ] All variants (markets, edge cases, A/B tests) are documented
- [ ] Edge cases are addressed (empty states, errors, long content, network delays)
- [ ] Pending questions are explicitly flagged (design + engineering)
- [ ] Ownership is stated (who, when, status)
- [ ] Test plan is included with specific success criteria
- [ ] Assets are organized and named; their locations are documented
- [ ] Open questions don't block engineering; they're flagged for parallel resolution
- [ ] Copy matrix includes all variations needed for implementation
- [ ] Interaction timing is specified where relevant (e.g., toast duration, animation speed, debounce intervals)
- [ ] For A/B tests: both variants are documented side-by-side with explicit differences called out
- [ ] Ethical review completed: design checked against anti-pattern catalog
- [ ] Measurement section completed: success metrics, counter-metrics, and instrumentation needs documented

---

## Voice and approach

**Intent over inventory.**
- The biggest anti-pattern in design documentation is the "real estate tour" — describing what's on screen without explaining why it's there. "There's a button with rounded corners in the top left" is inventory. "The primary CTA is positioned at the top of the viewport because research showed 68% of users abandon this flow before scrolling — the action needs to be visible on arrival" is design rationale.
- Every element in a spec should answer: why is this here? What problem does it solve for the user? What happens if we remove it?
- Bad: "On load, display 'Create your first project' in Headline 2 (24px, Inter Medium)."
- Good: "On load, display 'Create your first project' — new users in usability testing couldn't identify the starting action. This headline serves as the primary onboarding cue, using Headline 2 to establish it as the page's core instruction."
- If you can't articulate the intent behind a design decision, flag it as an open question rather than documenting it as settled.

**Structured and thorough, never bloated.**
- Say what matters. Omit generic descriptions that don't connect to user needs or design intent.

**Clear cross-functional ownership.**
- Explicitly state who made each decision and why.
- Call out constraints as design inputs, not limitations.

**Raise open questions explicitly.**
- Don't hide uncertainty; flag it.
- Distinguish between "design needs to decide" vs. "engineering needs to decide" vs. "requires data/research."

**Visual + logical rules.**
- Show designs, then explain the reasoning behind them.
- Make copy testable and implementable.

**Treat constraints as design inputs.**
- Performance requirements, accessibility needs, brand guidelines — these shape the spec, so make them visible.

---

## Scope boundaries

### This skill does:
- Document design decisions (don't make them)
- Organize and structure existing design work for implementation
- Write comprehensive specs, test plans, and asset packages
- Produce cross-functional presentations and alignment documents
- Flag open questions and dependencies transparently
- Map edge cases and write copy variations
- Conduct ethical review against Intent's anti-pattern catalog
- Connect specs to measurement frameworks from `/measure`

### This skill does NOT:
- Make design decisions (that's the designer's work)
- Write code or implementation details
- Conduct user research or validation (`/investigate`)
- Design new features (that requires `/strategize` or `/journey`)
- Provide implementation estimates (that's engineering's role)
- Define success metrics from scratch (`/measure` owns metric selection)
- Assess UX quality or heuristic compliance (`/evaluate`)

---

## When to use this skill

Trigger Specify when:
- **"Write the spec"** — Comprehensive design specification needed
- **"Prepare the handoff"** — Engineering needs everything ready to build
- **"Document this for engineering"** — Translate design into actionable specs
- **"What do we need for the design review?"** — Prepare materials for alignment meetings
- **"Build the test plan"** — Define success criteria and test audiences
- **"Write the copy matrix"** — Document all variations in one place
- **"What are the edge cases?"** — Design scenarios and copy for unusual situations
- **"Create a design package"** — Assemble spec, assets, and documentation
- **"For engineering" or "for implementation"** — Any handoff context

Not all sections are required for every handoff. Use what serves the project and audience.