/dev-specs - Implementation Specifications Skill

/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

Agent Skills: /dev-specs - Implementation Specifications

Install this agent skill to your local

Skill Files