/dev-specs - Implementation Specifications

Skill Awareness: See skills/_registry.md for all available skills.

Before: Ensure /debrief completed (BRD exists)

Auto: Runs /dev-scout if scout.md missing

After: Use /dev-coding for implementation

Generate precise implementation plans from BRD use cases. Creates per-UC specs with shared components.

When to Use

After /debrief created BRD use cases
After /dev-scout {feature} analyzed codebase
Before starting implementation
When onboarding engineers to a feature

Usage

/dev-specs auth                              # Generate specs for auth feature
/dev-specs auth UC-AUTH-001                  # Single use case only
/dev-specs billing --api=swagger.json        # With API spec file
/dev-specs payments --schema=schema.prisma   # With DB schema

Prerequisites

Before running, ensure:

plans/brd/ exists with use cases
plans/features/{feature}/ exists

Note: Scout is auto-triggered if missing (see Phase 0).

Input Files

The skill can accept additional context files:

Input	Flag	Purpose
API Spec	`--api=`	OpenAPI, Swagger, GraphQL schema
DB Schema	`--schema=`	Prisma, SQL, TypeORM entities
Design	`--design=`	Figma link, screenshots path
Docs	`--docs=`	External docs, wikis, READMEs
Env	`--env=`	Credentials for live API testing

Output Structure

plans/features/{feature}/
├── README.md              # Feature overview
├── scout.md               # From /dev-scout
│
└── specs/
    ├── README.md          # Index, implementation order, dependencies
    │
    ├── shared/            # Shared across all UCs
    │   ├── data-model.md  # Schema changes, entities
    │   ├── patterns.md    # Code patterns, conventions
    │   └── security.md    # Auth, validation, permissions
    │
    ├── UC-XXX-001-{slug}/ # Per use case
    │   ├── README.md      # Implementation plan
    │   ├── changes.md     # Files to create/modify
    │   └── tests.md       # Test cases
    │
    └── UC-XXX-002-{slug}/
        └── ...

Workflow

Phase 0: Check Dependencies & Graph Context

Before generating specs, verify prerequisites and gather context:

1. Check: plans/brd/ exists?
   → No: Error "Run /debrief first"

2. Check: plans/features/{feature}/ exists?
   → No: Error "Feature not found in BRD"

3. Check: plans/features/{feature}/scout.md exists?
   → No: Auto-run scout (see below)

4. Read: plans/docs-graph.json
   → Get related nodes and dependencies

Auto-Scout Logic:

If scout.md doesn't exist:

Notify user: "No scout found for {feature}, running analysis..."
Execute scout workflow (medium mode) for the feature
Save to plans/features/{feature}/scout.md
Continue to Phase 1

Docs-Graph Integration:

Read plans/docs-graph.json to understand:

What to Find	How It Helps
Use cases for feature	Know exactly which UCs to spec (`[[uc-auth-001]]`)
Existing specs	Avoid duplicates, find patterns
Dependencies	UCs that link to each other need coordinated specs
Related features	Cross-feature impacts (`[[feature-billing]]` links)

Example graph query for /dev-specs auth:

{
  "feature": "auth",
  "use_cases": ["uc-auth-001", "uc-auth-002", "uc-auth-003"],
  "existing_specs": [],
  "dependencies": {
    "uc-auth-002": ["uc-auth-001"],  // Signup depends on Login
    "uc-auth-003": ["uc-auth-001"]   // Forgot depends on Login
  },
  "cross_feature": ["feature-billing"]  // Auth linked from billing
}

This informs:

Implementation order (Login first, then Signup/Forgot)
Shared components (auth patterns used by billing)
What specs are already done vs. needed

Phase 1: Gather Context

Read BRD use cases for the feature
- plans/brd/use-cases/UC-{GROUP}-*.md
- Extract acceptance criteria, business rules
Read feature scout (if exists)
- plans/features/{feature}/scout.md
- Understand existing implementation
Read additional inputs (if provided)
- API specs → Extract endpoints, contracts
- DB schema → Understand data model
- Design docs → UI requirements
Ask clarifying questions using AskUserQuestion:

Q1: Implementation Scope

Backend only
Frontend only
Full-stack
API/Service only
Mobile app

Q2: Additional Context (multi-select)

Have API specs (Swagger/OpenAPI/GraphQL)
Have DB schema file
Have design files/links
Have existing documentation
None

Q3: Testing Approach

Unit tests only
Unit + Integration
Unit + Integration + E2E
No tests (docs only)

Phase 2: Analyze Impact

For each use case:

What's new? - Files/components to create
What changes? - Existing files to modify
What's shared? - Reusable across UCs
Dependencies? - What must exist first

Create impact summary:

## Impact Analysis

| UC | New Files | Modified | Dependencies |
|----|-----------|----------|--------------|
| UC-AUTH-001 | 5 | 2 | shared/data-model |
| UC-AUTH-002 | 3 | 1 | UC-AUTH-001 |

Phase 3: Generate Shared Specs

Create specs/shared/ files:

data-model.md:

# Data Model

## New Entities

### User
| Field | Type | Notes |
|-------|------|-------|
| id | uuid | PK |
| email | string | Unique |
| passwordHash | string | bcrypt |

## Schema Changes

```sql
-- Migration: add_users_table
CREATE TABLE users (
    id UUID PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    ...
);

Relationships

{Describe entity relationships}


**patterns.md:**
```markdown
# Implementation Patterns

## Code Style
- Follow existing patterns from scout
- {Specific conventions}

## Error Handling
- {How to handle errors}
- {User feedback patterns}

## API Patterns (if applicable)
- {Request/response format}
- {Authentication headers}

## State Management (if applicable)
- {State patterns}
- {Data fetching}

security.md:

# Security Considerations

## Authentication
- {How auth works}

## Authorization
- {Permission model}

## Data Validation
- {Input validation rules}

## Sensitive Data
- {What to protect, how}

Phase 4: Generate UC Specs

For each use case, create folder with:

README.md (Implementation Plan):

# UC-{GROUP}-{NNN}: {Title}

> **Feature**: [[feature-{feature}]]
> **BRD**: [[uc-{group}-{nnn}]]
> **Status**: Draft

## Overview
{What this UC implements}

## Business Requirements
{From BRD - acceptance criteria}

## Current State
{From scout - what exists}

## Implementation Plan

### 1. {Step 1}
- {Detail}
- {Detail}

### 2. {Step 2}
- {Detail}

## API Contract (if applicable)

### {Method} {Endpoint}

**Request:**
```json
{
    "field": "type"
}

Response:

{
    "field": "type"
}

Errors:

Code	Reason
400	Invalid input
401	Unauthorized

UI Components (if applicable)

Component	Purpose	Props
{Name}	{Purpose}	{Key props}

Edge Cases

{Edge case 1}
{Edge case 2}

Dependencies

{What must exist first}

Acceptance Mapping

BRD Criteria	Implementation
Given X, When Y, Then Z	{How implemented}


**changes.md:**
```markdown
# File Changes

## New Files

| File | Purpose |
|------|---------|
| `src/api/auth/login.ts` | Login endpoint |
| `src/components/LoginForm.tsx` | Login form UI |

## Modified Files

| File | Change |
|------|--------|
| `src/lib/auth.ts` | Add login function |
| `prisma/schema.prisma` | Add User model |

## File Tree Preview

src/ ├── api/ │ └── auth/ │ └── login.ts # NEW ├── components/ │ └── auth/ │ └── LoginForm.tsx # NEW └── lib/ └── auth.ts # MODIFIED

tests.md:

# Test Plan

## Unit Tests

| Test | File | Description |
|------|------|-------------|
| Login validation | `login.test.ts` | Validate email/password |
| Token generation | `auth.test.ts` | JWT token creation |

## Integration Tests

| Test | Description |
|------|-------------|
| Login flow | POST /api/auth/login with valid creds |
| Invalid login | POST /api/auth/login with wrong password |

## E2E Tests (if applicable)

| Scenario | Steps |
|----------|-------|
| User login | Navigate to /login, enter creds, verify redirect |

## Test Data

```json
{
    "validUser": {
        "email": "test@example.com",
        "password": "TestPass123!"
    }
}

Coverage Target

Unit: 80%+
Integration: Key paths
E2E: Happy path + critical errors


### Phase 5: Generate Specs Index

Create `specs/README.md`:

```markdown
# {Feature} - Implementation Specs

> **Feature**: [[feature-{feature}]]
> **Generated**: {date}
> **Use Cases**: {count}

## Overview
{Brief description of the feature implementation}

## Implementation Order

| Order | UC | Title | Depends On | Estimate |
|-------|-----|-------|------------|----------|
| 1 | [[uc-auth-001]] | Login | shared/* | - |
| 2 | [[uc-auth-002]] | Signup | [[uc-auth-001]] | - |
| 3 | [[uc-auth-003]] | Forgot Password | [[uc-auth-001]] | - |

## Shared Specs
- [Data Model](./shared/data-model.md)
- [Patterns](./shared/patterns.md)
- [Security](./shared/security.md)

## Dependencies Graph

```mermaid
flowchart TD
    shared[shared/*] --> UC001[UC-AUTH-001]
    UC001 --> UC002[UC-AUTH-002]
    UC001 --> UC003[UC-AUTH-003]

Summary

Metric	Count
Total Use Cases	{n}
New Files	{n}
Modified Files	{n}
Tests	{n}

Notes

{Any implementation notes, risks, considerations}


### Phase 6: Summary

Output:
- Specs created
- Use cases covered
- Files that will change
- Dependencies identified
- Next steps

## Tools Used

| Tool | Purpose |
|------|---------|
| `Read` | BRD, scout, input files |
| `Glob` | Find related files |
| `Write` | Create spec files |
| `AskUserQuestion` | Clarify scope |
| `WebFetch` | Fetch external docs (if URL) |

## Integration with Other Skills

| Skill | Relationship |
|-------|--------------|
| `/debrief` | Provides use cases (input) |
| `/dev-scout` | Provides codebase context (input) |
| `/diagram` | Can validate mermaid in specs |

## Tips

- Run `/dev-scout {feature}` first for better context
- Provide API specs when available for accurate contracts
- Keep each UC spec focused - one job per UC
- Estimates are left blank for team to fill

## References

- `references/spec-templates.md` - Template structures
- `references/checklist.md` - Spec completeness checklist