name: writing-specs description: Use when creating feature specifications after brainstorming - generates lean spec documents that reference constitutions heavily, link to external docs instead of embedding examples, and focus on WHAT not HOW (implementation plans handled separately)

Writing Specifications

Overview

A specification defines WHAT to build and WHY. It is NOT an implementation plan.

Core principle: Reference constitutions, link to docs, keep it lean. The /plan command handles task decomposition.

Spec = Requirements + Architecture Plan = Tasks + Dependencies

When to Use

Use this skill when:

Creating specs/{run-id}-{feature-slug}/spec.md after brainstorming
Called from /spectacular:spec slash command (after brainstorming phases 1-3)
Need to document feature requirements and architecture

Do NOT use for:

Implementation plans with task breakdown → Use /spectacular:plan instead
API documentation → Goes in code comments or separate docs
Runbooks or operational guides → Different document type

Spec Structure

# Feature: {Feature Name}

**Status**: Draft
**Created**: {date}

## Problem Statement

**Current State:**
{What exists today and what's missing/broken}

**Desired State:**
{What we want to achieve}

**Gap:**
{Specific problem this feature solves}

## Requirements

> **Note**: All features must follow @docs/constitutions/current/

### Functional Requirements
- FR1: {specific requirement}
- FR2: {specific requirement}

### Non-Functional Requirements
- NFR1: {performance/security/DX requirement}
- NFR2: {performance/security/DX requirement}

## Architecture

> **Layer boundaries**: @docs/constitutions/current/architecture.md
> **Required patterns**: @docs/constitutions/current/patterns.md

### Components

**New Files:**
- `src/lib/models/{name}.ts` - {purpose}
- `src/lib/services/{name}-service.ts` - {purpose}
- `src/lib/actions/{name}-actions.ts` - {purpose}

**Modified Files:**
- `{path}` - {what changes}

### Dependencies

**New packages:**
- `{package}` - {purpose}
- See: {link to official docs}

**Schema changes:**
- {migration name} - {purpose}
- Rules: @docs/constitutions/current/schema-rules.md

### Integration Points

- Auth: Uses existing Auth.js setup
- Database: Prisma client per @docs/constitutions/current/tech-stack.md
- Validation: Zod schemas per @docs/constitutions/current/patterns.md

## Acceptance Criteria

**Constitution compliance:**
- [ ] All patterns followed (@docs/constitutions/current/patterns.md)
- [ ] Architecture boundaries respected (@docs/constitutions/current/architecture.md)
- [ ] Testing requirements met (@docs/constitutions/current/testing.md)

**Feature-specific:**
- [ ] {criterion for this feature}
- [ ] {criterion for this feature}
- [ ] {criterion for this feature}

**Verification:**
- [ ] All tests pass
- [ ] Linting passes
- [ ] Feature works end-to-end

## Open Questions

{List any unresolved questions or decisions needed}

## References

- Architecture: @docs/constitutions/current/architecture.md
- Patterns: @docs/constitutions/current/patterns.md
- Schema Rules: @docs/constitutions/current/schema-rules.md
- Tech Stack: @docs/constitutions/current/tech-stack.md
- Testing: @docs/constitutions/current/testing.md
- {External SDK}: {link to official docs}

Iron Laws

1. Reference, Don't Duplicate

❌ NEVER recreate constitution rules in the spec

The architecture has three layers:

Models: Data access with Prisma
Services: Business logic
Actions: Input validation with Zod

</Bad>

<Good>
```markdown
## Architecture

> **Layer boundaries**: @docs/constitutions/current/architecture.md

Components follow the established 3-layer pattern.

2. Link to Docs, Don't Embed Examples

❌ NEVER include code examples from external libraries

import { z } from 'zod';

export const schema = z.object({
  name: z.string().min(3),
  email: z.string().email()
});

</Bad>

<Good>
```markdown
### Validation

Use Zod schemas per @docs/constitutions/current/patterns.md

See: https://zod.dev for object schema syntax

3. No Implementation Plans

❌ NEVER include task breakdown or migration phases

Phase 1: Database Schema

Create Prisma migration
Run migration
Verify indexes

Phase 2: Backend Implementation

...

</Bad>

<Good>
```markdown
## Dependencies

**Schema changes:**
- Migration: `init_rooms` - Add Room, RoomParticipant, WaitingListEntry models

Implementation order determined by `/plan` command.

4. No Success Metrics

❌ NEVER include adoption metrics, performance targets, or measurement strategies

Adoption: 80% of users use feature within first month
Performance: Page loads in <500ms
Engagement: <5% churn rate

</Bad>

<Good>
```markdown
## Non-Functional Requirements

- NFR1: Page load performance <500ms (measured per @docs/constitutions/current/testing.md)
- NFR2: Support 1000 concurrent users

Common Mistakes

Mistake	Why It's Wrong	Fix
Including full Prisma schemas	Duplicates what goes in code	List model names + purposes, reference schema-rules.md
Writing test code examples	Shows HOW not WHAT	List what to test, reference testing.md for how
Explaining ts-pattern syntax	Already in patterns.md	Reference patterns.md, list where pattern applies
Creating `/notes` subdirectory	Violates single-file principle	Keep spec lean, remove supporting docs
Adding timeline estimates	That's project management	Focus on requirements and architecture

Rationalization Table

Excuse	Reality
"Thorough means showing complete code"	Thorough = complete requirements. Code = implementation.
"Spec needs examples so people understand"	Link to docs. Don't copy-paste library examples.
"Migration plan shows full picture"	`/plan` command handles decomposition. Spec = WHAT not HOW.
"Include constitutions for context"	Constitutions exist to avoid duplication. Reference, don't recreate.
"Testing code shows approach"	testing.md shows approach. Spec lists WHAT to test.
"Metrics demonstrate value"	NFRs show requirements. Metrics = measurement strategy (different doc).
"More detail = more helpful"	More detail = harder to maintain. Lean + links = durable.

Red Flags - STOP and Fix

Seeing any of these? Delete and reference instead:

Full code examples from libraries (Zod, Prisma, Socket.io, etc.)
Migration phases or implementation steps
Success metrics or adoption targets
Recreated architecture explanations
Test implementation code
Files in specs/{run-id}-{feature-slug}/notes/ directory
Spec > 300 lines (probably duplicating constitutions)

All of these mean: Too much implementation detail. Focus on WHAT not HOW.

Workflow Integration

This skill is called from /spectacular:spec command:

User runs: /spectacular:spec {feature description}
Brainstorming: Phases 1-3 run (understanding, exploration, design)
This skill: Generate specs/{run-id}-{feature-slug}/spec.md
User reviews: Check spec for completeness
Next step: /spectacular:plan @specs/{run-id}-{feature-slug}/spec.md for task decomposition

Quality Checklist

Before finalizing spec:

Problem statement shows current → desired state gap
All FRs and NFRs are testable/verifiable
Architecture section lists files (not code examples)
All constitution rules referenced (not recreated)
All external libraries linked to docs (not copied)
No implementation plan (saved for /spectacular:plan)
No success metrics or timelines
Single file at specs/{run-id}-{feature-slug}/spec.md
Spec < 300 lines (if longer, check for duplication)

The Bottom Line

Specs define WHAT and WHY. Plans define HOW and WHEN.

Reference heavily. Link to docs. Keep it lean.

If you're copy-pasting code or recreating rules, you're writing the wrong document.

writing-specs

$ Installer