name	feature-specification
description	Iterative feature design and specification process before development. Use when exploring new features from Linear backlog, evaluating approaches, researching best practices, or designing UI/UX. Produces comprehensive specification documents.
allowed-tools	Read, Grep, Glob, WebSearch, WebFetch, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__linear__get_issue, mcp__linear__list_issues

Feature Specification & Design Skill

Guide for iterative feature exploration, design, and specification before writing any code. This skill helps research, evaluate options, and document comprehensive specifications for new features.

Core Philosophy: Explore thoroughly, design carefully, specify completely—then code confidently.

When to Use This Skill

Use this skill when:

Starting a new feature from Linear backlog
Evaluating multiple solution approaches
Researching best practices for a technology
Designing UI/UX for new functionality
Refactoring significant functionality
Need to explore options before committing to an approach
Want to document a feature specification

DO NOT use this skill when:

You already have a clear specification and are ready to code
Making trivial bug fixes
The approach is already decided

Iterative Design Process

This is an iterative conversation where we progressively refine the design from broad concept to detailed specification.

Phase 1: Discovery & Context Gathering

Goal: Understand the problem and gather all relevant context

Step 1.1: Initial Context

Ask user to provide:

Feature description (from Linear or verbal)
Problem being solved (why does this feature exist?)
User personas (who will use this?)
Success criteria (what defines "done"?)
Constraints (technical, time, budget)

If from Linear, fetch the issue:

// Use Linear MCP tool
const issue = await getLinearIssue(issueId)

Step 1.2: Existing System Analysis

Explore existing codebase:

Find similar features using Grep/Glob
Review existing patterns that could be reused
Check existing UI components that could be adapted
Identify integration points with current system

// Example searches
Grep: pattern="eventRegistration" // Find similar features
Glob: pattern="**/components/events/**/*.tsx" // Find event components
Read: // Examine relevant existing code

Step 1.3: Technical Context

Database schema - What models are involved?
API routes - What endpoints will be needed?
Authentication/RBAC - What permissions required?
Performance requirements - Data size, response times
Dependencies - External libraries or services

Output: Context Summary Document

# Feature Context: [Feature Name]

## Problem Statement
[Clear description of the problem]

## User Stories
- As a [persona], I want to [action] so that [benefit]

## Current System
- Related features: [list]
- Existing components: [list]
- Database models: [list]
- Integration points: [list]

## Constraints
- Technical: [list]
- Time: [estimate]
- Performance: [requirements]

Phase 2: Research & Best Practices

Goal: Research best practices, explore existing solutions, gather inspiration

Step 2.1: Library Research (Context7)

For technology-specific features, research best practices:

// Example: If implementing authentication flow
1. Resolve library ID
   const nextAuthLibs = await resolveLibraryId("next-auth", query)

2. Query best practices
   const docs = await queryDocs("/nextjs/next-auth", "authentication flow patterns")

3. Gather patterns
   - Standard authentication flows
   - Session management approaches
   - Error handling patterns
   - Security best practices

Common Research Areas:

Next.js: Server components, routing, data fetching, caching
React: State management, form handling, performance
Prisma: Schema design, query optimization, transactions
Tailwind: Component patterns, responsive design, animations
Testing: Testing strategies, mock patterns, E2E flows

Step 2.2: Web Research

For UI/UX or general patterns:

// Example searches
WebSearch: "best practices for event registration forms 2025"
WebSearch: "React table component performance optimization"
WebSearch: "progressive form disclosure patterns"

// Review relevant articles
WebFetch: url="https://..."

Step 2.3: Competitive Analysis

How do similar apps solve this?
What patterns are users familiar with?
What are common pitfalls to avoid?

Output: Research Summary

# Research Findings: [Feature Name]

## Best Practices
1. [Practice] - Source: [library/article]
2. [Practice] - Source: [library/article]

## Recommended Patterns
- **Pattern Name**: Description and rationale
- **Anti-patterns to avoid**: What NOT to do

## Libraries/Tools Considered
- [Library]: Pros, Cons, Decision

Phase 3: Solution Options Exploration

Goal: Explore multiple solution approaches, evaluate trade-offs

Step 3.1: Generate Options

Create 2-4 solution approaches, each with:

Architecture: How would it work?
Components: What parts are needed?
Data flow: How does data move through the system?
UI/UX: How does the user interact?
Pros: Benefits of this approach
Cons: Drawbacks or risks
Complexity: Implementation difficulty (Low/Medium/High)
Performance: Expected performance characteristics

Example Template:

## Option 1: [Approach Name]

### Architecture
[Server components + API routes + service layer diagram]

### Components
- ServerComponent: EventRegistrationPage
- ClientComponent: RegistrationForm
- Service: EventRegistrationService
- API: /api/events/[id]/register

### Data Flow
1. User navigates → Server component fetches event data (optimized select)
2. Client component renders form
3. Form submission → API route
4. API validates → Service layer processes → Database update
5. Redirect to confirmation page

### UI/UX Flow
[Step-by-step user flow with wireframes/mockups]

### Pros
- Simple to understand
- Follows existing patterns
- Easy to test

### Cons
- Multiple round trips
- Could be slow for large datasets

### Complexity
Medium - Standard CRUD with validation

### Performance Impact
- Initial load: ~500ms
- Form submission: ~1s
- Data size: ~10KB per registration

Step 3.2: UI/UX Design Options

For each approach, design the UI following Dockside standards:

Responsive Design Requirements:

Mobile-first approach (0-640px)
Tablet adaptations (641-1024px)
Desktop optimizations (1025px+)

Component Variants (from Crew UI System):

default: Standard padding (p-4), typography (text-sm), height (h-10)
compact: Tight padding (p-2), small text (text-xs), reduced height (h-8)
dense: Very tight (p-1), high-contrast borders for scanning
mobile: Stacked card layout on all screen sizes

UI Pattern Checklist:

Responsive layout (mobile/tablet/desktop)
Component hierarchy defined
State management approach (local vs. global)
Loading states
Error states
Empty states
Success feedback
Accessibility (ARIA labels, keyboard navigation)
Icons (Lucide React)
Color scheme (follows design system)
Typography (heading levels, body text)

Performance Optimization:

Data fetching strategy (optimized select)
Pagination for lists
Code splitting for heavy components
Memoization for expensive computations
Virtual scrolling for long lists
Image optimization (Next.js Image)
Debounced inputs for search/filter

Example UI Specification:

### UI Design: Registration Form

#### Component Hierarchy

EventRegistrationPage (Server) ├── EventHeader (Server) │ ├── EventTitle │ └── EventMetadata └── RegistrationFormClient (Client) ├── SailorSearchInput (variant="default") ├── ClassSelector ├── BoatDetailsSection │ ├── SailNumberInput │ └── BoatNameInput ├── CrewTable (variant="default") │ └── SailorSearchInput (variant="compact") └── SubmitButton


#### Responsive Behavior
- **Mobile (< 640px)**:
  - Single column layout
  - Stacked sections
  - Full-width inputs
  - Large touch targets (`h-12`)
  - CrewTable switches to card layout

- **Tablet (641-1024px)**:
  - Two-column layout for boat details
  - Standard input heights (`h-10`)
  - CrewTable uses compact variant

- **Desktop (1025px+)**:
  - Full table layout for crew
  - Inline validation messages
  - Keyboard shortcuts enabled

#### State Management
- **Local State** (useState):
  - Form field values
  - Validation errors
  - UI toggles (expanded sections)

- **Server State** (fetched):
  - Event data (optimized with select)
  - Available classes
  - Sailor search results

#### Data Fetching Optimization
```typescript
// EventRegistrationPage (Server Component)
const event = await prisma.event.findUnique({
  where: { id },
  select: {
    id: true,
    name: true,
    startDate: true,
    classes: {
      select: {
        id: true,
        class: {
          select: {
            id: true,
            name: true,
            boatType: true,
            crewRules: true, // Required for crew validation
          }
        }
      }
    },
    _count: {
      select: {
        registrations: true
      }
    }
  }
})

// Transform to view model (~ 5KB)
const viewModel = {
  id: event.id,
  name: event.name,
  startDate: event.startDate,
  classes: event.classes.map(c => ({
    id: c.class.id,
    name: c.class.name,
    crewRequirements: c.class.crewRules
  })),
  stats: {
    currentRegistrations: event._count.registrations
  }
}

Performance Targets

Initial page load: < 1s
Form submission: < 2s
Sailor search: < 500ms
Prop size: < 20KB


#### Step 3.3: Evaluate Trade-offs

Create comparison matrix:

| Criterion | Option 1 | Option 2 | Option 3 |
|-----------|----------|----------|----------|
| **Complexity** | Medium | Low | High |
| **Performance** | Good (1s) | Excellent (<500ms) | Fair (2s) |
| **Maintainability** | High | High | Medium |
| **Extensibility** | High | Medium | Very High |
| **User Experience** | Good | Excellent | Good |
| **Development Time** | 2 weeks | 1 week | 3 weeks |
| **Risk** | Low | Low | Medium |
| **Recommendation** | ⭐ Preferred | Acceptable | Future consideration |

**Output**: Solution Options Document
```markdown
# Solution Options: [Feature Name]

## Option 1: [Name] ⭐ RECOMMENDED
[Full details as template above]

## Option 2: [Name]
[Full details]

## Option 3: [Name]
[Full details]

## Comparison Matrix
[Table above]

## Recommendation
We recommend **Option 1** because:
- [Reason 1]
- [Reason 2]
- [Reason 3]

Risk mitigation:
- [Risk]: [Mitigation strategy]

Phase 4: Detailed Specification

Goal: Create implementation-ready specification document

Step 4.1: Architecture Specification

# Technical Specification: [Feature Name]

## Architecture Overview

### Component Structure

/app /events /[id] /register page.tsx # Server component

/components /events /registration RegistrationForm.tsx # Client component SailorSearchInput.tsx # Reusable ClassSelector.tsx # New CrewTable.tsx # Existing (use variant)

/server /services eventRegistrationService.ts # Business logic

/lib /validations registrationSchema.ts # Zod schemas

/types /viewModels registrationViewModel.ts # UI types


### Data Flow Diagram

[User] → [Page (Server)] → [Fetch Event Data] → [Transform to ViewModel] ↓ [RegistrationForm (Client)] → [User Input] → [Validate] ↓ [Submit] → [API Route] → [Service Layer] → [Database] ↓ [Redirect to Confirmation]


### Database Schema Changes
```prisma
// No changes required - uses existing Registration model

// OR if changes needed:
model Registration {
  // ... existing fields
  crewMembers   CrewMember[]  // New relation
}

model CrewMember {
  id              String       @id @default(cuid())
  registrationId  String
  sailorId        String
  role            CrewRole
  // ...
}

API Endpoints

POST /api/events/[eventId]/register
  Request:
    {
      classId: string
      sailNumber: string
      boatName: string
      crew: { sailorId: string, role: string }[]
    }
  Response:
    { success: true, registrationId: string }
    OR
    { success: false, error: string }

GET /api/events/[eventId]/registration-status
  Response:
    { canRegister: boolean, reason?: string }

Service Layer

// server/services/eventRegistrationService.ts

interface CreateRegistrationInput {
  eventId: string
  sailorId: string
  classId: string
  sailNumber: string
  boatName: string
  crew: CrewMemberInput[]
}

interface ServiceResult<T> {
  success: boolean
  data?: T
  error?: string
}

export async function createRegistration(
  input: CreateRegistrationInput,
  userId: string
): Promise<ServiceResult<Registration>> {
  // 1. Validate input
  // 2. Check permissions (hasRole)
  // 3. Validate business rules:
  //    - Event is open for registration
  //    - Class is available for event
  //    - Sailor not already registered
  //    - Crew size matches class rules
  // 4. Create registration in transaction
  // 5. Send confirmation email
  // 6. Audit log
  // 7. Return result
}


#### Step 4.2: UI/UX Specification

```markdown
## User Interface Specification

### Wireframes
[Include ASCII wireframes or reference to Figma/design files]

┌────────────────────────────────────────────┐ │ [Event Name] [X Close]│ ├────────────────────────────────────────────┤ │ │ │ Registration for [Event Name] │ │ [Date] at [Venue] │ │ │ │ Select Class: │ │ ┌──────────────────────────────────────┐ │ │ │ [▼ Laser Standard] │ │ │ └──────────────────────────────────────┘ │ │ │ │ Boat Details: │ │ Sail Number: [] Required │ │ Boat Name: [] Optional │ │ │ │ Crew (Optional for this class): │ │ ┌──────────────────────────────────────┐ │ │ │ Search sailor... [🔍] │ │ │ │ │ │ │ │ [+ Add Crew Member] │ │ │ └──────────────────────────────────────┘ │ │ │ │ [Cancel] [Register] → │ └────────────────────────────────────────────┘


### Component Specifications

#### RegistrationForm
- **Type**: Client Component
- **Props**: `{ event: EventViewModel }`
- **State**:
  - `selectedClass: string | null`
  - `sailNumber: string`
  - `boatName: string`
  - `crew: CrewMember[]`
  - `errors: Record<string, string>`
  - `isSubmitting: boolean`
- **Validation**:
  - Sail number: Required, alphanumeric, max 10 chars
  - Class: Required
  - Crew: Validate against class rules
- **Error Handling**:
  - Inline field errors (red text below input)
  - Form-level errors (red banner at top)
  - Network errors (retry mechanism)

#### SailorSearchInput
- **Type**: Client Component
- **Variant**: `default`
- **Features**:
  - Debounced search (300ms)
  - Autocomplete dropdown
  - Keyboard navigation (↑↓ + Enter)
  - Shows sailor name + club
  - Recent selections cached locally

### Accessibility
- **ARIA Labels**: All inputs properly labeled
- **Keyboard Navigation**: Full keyboard support
- **Screen Readers**: Meaningful labels and descriptions
- **Focus Management**: Logical tab order
- **Error Announcements**: Errors announced to screen readers

### Performance Requirements
- **Initial Load**: < 1s (LCP)
- **Form Submission**: < 2s
- **Sailor Search**: < 500ms
- **Prop Size**: < 20KB
- **Bundle Size**: < 50KB (code-split)

Step 4.3: Testing Strategy

## Testing Specification

### Test Coverage

#### Unit Tests (70%)
```typescript
// __tests__/services/eventRegistrationService.test.ts
describe('EventRegistrationService', () => {
  describe('createRegistration', () => {
    it('should create registration with valid input', async () => {
      // Use centralized factories
      const input = createMockRegistrationInput()
      const result = await createRegistration(input, userId)
      expect(result.success).toBe(true)
    })

    it('should reject registration when event is full', async () => {
      // Test business rule
    })

    it('should validate crew size against class rules', async () => {
      // Test crew validation
    })
  })
})

// __tests__/components/RegistrationForm.test.tsx
describe('RegistrationForm', () => {
  it('should validate sail number format', async () => {
    // Form validation test
  })

  it('should show error when class not selected', async () => {
    // Validation test
  })
})

Integration Tests (20%)

Test API route with real database
Test full registration flow
Test email sending
Test audit logging

E2E Tests (10%)

Complete user registration flow
Error handling flows
Mobile responsive behavior

Test Data

Use centralized test utilities:

createMockEvent() - From testDataFactories.ts
setupTestDatabase() - From testDatabaseHelpers.ts
cleanupTestContext() - From testCleanupHelpers.ts


#### Step 4.4: Implementation Plan

```markdown
## Implementation Plan

### Phase 1: Foundation (2-3 days)
**TDD Required**: Write tests BEFORE implementation

1. **Database Schema** (if changes needed)
   - [ ] Update Prisma schema
   - [ ] Create migration
   - [ ] Update seed data

2. **Service Layer**
   - [ ] Write service tests (TDD)
   - [ ] Implement eventRegistrationService
   - [ ] Add validation logic
   - [ ] Add audit logging

3. **API Routes**
   - [ ] Write API tests (TDD)
   - [ ] Implement POST /api/events/[id]/register
   - [ ] Add authentication checks
   - [ ] Add input validation

### Phase 2: UI Components (3-4 days)
**TDD Required**: Component tests before implementation

1. **Server Components**
   - [ ] Write page tests
   - [ ] Create EventRegistrationPage
   - [ ] Optimize data fetching (select)
   - [ ] Create view models

2. **Client Components**
   - [ ] Write component tests (TDD)
   - [ ] Implement RegistrationForm
   - [ ] Implement ClassSelector
   - [ ] Adapt CrewTable (use variant="default")
   - [ ] Implement validation UI

3. **Responsive Design**
   - [ ] Mobile layout (<640px)
   - [ ] Tablet layout (641-1024px)
   - [ ] Desktop layout (1025px+)
   - [ ] Test on real devices

### Phase 3: Integration & Testing (2 days)

1. **Integration Testing**
   - [ ] Full registration flow test
   - [ ] Error handling tests
   - [ ] Performance testing

2. **E2E Testing**
   - [ ] Playwright tests for complete flow
   - [ ] Mobile device testing
   - [ ] Accessibility testing

3. **Performance Optimization**
   - [ ] Measure prop sizes (< 20KB)
   - [ ] Measure load times (< 1s)
   - [ ] Optimize as needed

### Phase 4: Polish & Launch (1 day)

1. **Code Review**
   - [ ] Run quality-nazi skill
   - [ ] Peer review
   - [ ] Address feedback

2. **Documentation**
   - [ ] Update user documentation
   - [ ] Add inline code comments
   - [ ] Update API documentation

3. **Deploy**
   - [ ] Deploy to staging
   - [ ] Smoke testing
   - [ ] Deploy to production
   - [ ] Monitor metrics

### Total Estimate: 8-10 days

Step 4.5: Risk Assessment

## Risk Assessment & Mitigation

### Technical Risks

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| Crew validation complexity | High | Medium | Start simple, iterate; comprehensive tests |
| Performance with large events | High | Low | Pagination, optimized queries, load testing |
| Mobile UX issues | Medium | Medium | Mobile-first design, real device testing |
| Data serialization issues | High | Low | Monitor prop sizes, use view models |

### Business Risks

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| User confusion | Medium | Medium | User testing, clear instructions |
| Low adoption | High | Low | Training, documentation, support |
| Edge cases not covered | Medium | Medium | Comprehensive testing, phased rollout |

Final Output: Complete Specification Document

# Feature Specification: [Feature Name]

## Executive Summary
[1-2 paragraph summary of feature and recommendation]

## Context & Requirements
[From Phase 1]

## Research & Best Practices
[From Phase 2]

## Solution Options & Recommendation
[From Phase 3]

## Technical Specification
[From Phase 4.1]

## UI/UX Specification
[From Phase 4.2]

## Testing Strategy
[From Phase 4.3]

## Implementation Plan
[From Phase 4.4]

## Risk Assessment
[From Phase 4.5]

## Sign-off
Ready for implementation: [ ]
Reviewed by: [stakeholder]
Date: [date]

Skill Usage Guidelines

Iterative Workflow

Start Broad: Begin with high-level problem statement
Progressively Refine: Add detail through conversation
Research Together: Explore best practices collaboratively
Evaluate Options: Discuss trade-offs
Specify in Detail: Document everything before coding

Questions to Guide Conversation

Discovery Phase:

What problem are we solving?
Who are the users?
What are the constraints?
What exists already that we can build on?

Research Phase:

What are best practices for this pattern?
How do similar apps solve this?
What libraries should we use?
What are common pitfalls?

Design Phase:

What are our options?
What are the trade-offs?
How does this perform?
How does this look on mobile?

Specification Phase:

What components do we need?
What's the data flow?
How do we test this?
What could go wrong?

Anti-Patterns to Avoid

❌ Don't:

Jump straight to implementation
Choose first solution without exploring options
Ignore performance implications
Skip UI/UX design phase
Forget about mobile responsive design
Neglect to research best practices
Write specification alone without user input

✅ Do:

Iterate progressively
Research thoroughly (Context7, web, existing code)
Explore multiple options
Design UI/UX following Dockside standards
Optimize for performance from the start
Include user in conversation
Document everything before coding

Integration with Other Skills

After completing specification:

Review with stakeholder for approval
Use quality-nazi when ready to implement
Follow development-guidelines during implementation
Reference specification throughout development

Output Artifacts

This skill produces comprehensive specification documents that should be stored in /documentation/features/[feature-name]/ rather than in the skills folder.

The documents include:

Context Summary - Problem statement and requirements
Research Findings - Best practices and patterns
Solution Options - Multiple approaches with trade-offs
Technical Specification - Architecture and implementation details
UI/UX Specification - Wireframes and responsive design
Testing Strategy - Comprehensive test plan
Implementation Plan - Phased development approach
Risk Assessment - Potential issues and mitigations

File Location: /documentation/features/[feature-name]/SPEC_[FEATURE_NAME].md

Example: For membership settings clarification, store at: /documentation/features/memberships/SPEC_MEMBERSHIP_SETTINGS_CLARIFICATION.md

Remember: The goal is to explore thoroughly and design carefully so that implementation is straightforward and confident. Take your time in this phase—it's cheaper to change a design than to refactor code.

feature-specification

Install Skill

SKILL.md