writing-specs

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:

• Invoked from /spectacular:spec slash command
• Creating a new feature specification from scratch
• Need the complete spec workflow (Run ID, worktree, brainstorm, spec, validation)

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

Announce: "I'm using the writing-specs skill to create a feature specification."

Workspace Detection

Before starting the spec workflow, detect the workspace mode:

# Detect workspace mode
REPO_COUNT=$(find . -maxdepth 2 -name ".git" -type d 2>/dev/null | wc -l | tr -d ' ')
if [ "$REPO_COUNT" -gt 1 ]; then
  echo "Multi-repo workspace detected ($REPO_COUNT repos)"
  WORKSPACE_MODE="multi-repo"
  WORKSPACE_ROOT=$(pwd)
  # List detected repos
  find . -maxdepth 2 -name ".git" -type d | xargs -I{} dirname {} | sed 's|^\./||'
else
  echo "Single-repo mode"
  WORKSPACE_MODE="single-repo"
fi

Single-repo mode (current behavior):

• Specs stored in specs/{runId}-{feature}/spec.md at repo root
• Worktree created at .worktrees/{runId}-main/
• Constitution referenced from @docs/constitutions/current/

Multi-repo mode (new behavior):

• Specs stored in ./specs/{runId}-{feature}/spec.md at WORKSPACE root
• NO worktree created (specs live at workspace level, not inside any repo)
• Each repo's constitution referenced separately

Constitution Adherence

All specifications MUST follow: @docs/constitutions/current/

• architecture.md - Layer boundaries, project structure
• patterns.md - Mandatory patterns (next-safe-action, ts-pattern, etc.)
• schema-rules.md - Database design philosophy
• tech-stack.md - Approved libraries and versions
• testing.md - Testing requirements

The Process

Step 0: Generate Run ID

First action: Generate a unique run identifier for this spec.

# Generate 6-char hash from feature name + timestamp
TIMESTAMP=$(date +%s)
RUN_ID=$(echo "{feature-description}-$TIMESTAMP" | shasum -a 256 | head -c 6)
echo "RUN_ID: $RUN_ID"

CRITICAL: Execute this entire block as a single multi-line Bash tool call. The comment on the first line is REQUIRED - without it, command substitution $(...) causes parse errors.

Store for use in:

• Spec directory name: specs/{run-id}-{feature-slug}/
• Spec frontmatter metadata
• Plan generation
• Branch naming during execution

Announce: "Generated RUN_ID: {run-id} for tracking this spec run"

Step 0.5: Create Isolated Worktree

Announce: "Creating isolated worktree for this spec run..."

Multi-repo mode: Skip worktree creation. Specs live at workspace root, not inside any repo.

if [ "$WORKSPACE_MODE" = "multi-repo" ]; then
  echo "Multi-repo mode: Specs stored at workspace root, no worktree needed"
  mkdir -p specs/${RUN_ID}-${FEATURE_SLUG}
  # Skip to Step 1 (brainstorming)
fi

Single-repo mode: Continue with worktree creation as normal.

Create worktree for isolated development:

1. Create branch using git-spice:

   • Use using-git-spice skill to create branch {runId}-main from current branch
   • Branch name format: {runId}-main (e.g., abc123-main)

2. Create worktree:

   # Create worktree at .worktrees/{runId}-main/
   git worktree add .worktrees/${RUN_ID}-main ${RUN_ID}-main
   

3. Error handling:

   • If worktree already exists: "Worktree {runId}-main already exists. Remove it first with git worktree remove .worktrees/{runId}-main or use a different feature name."
   • If worktree creation fails: Report the git error details and exit

Working directory context:

• All subsequent file operations happen in .worktrees/{runId}-main/
• Brainstorming and spec generation occur in the worktree context
• Main repository working directory remains unchanged

Announce: "Worktree created at .worktrees/{runId}-main/ - all work will happen in isolation"

Step 0.6: Install Dependencies in Worktree

REQUIRED: Each worktree needs dependencies installed before work begins.

1. Check CLAUDE.md for setup commands:

   Look for this pattern in the project's CLAUDE.md:

   ## Development Commands
   
   ### Setup
   
   - **install**: `bun install`
   - **postinstall**: `npx prisma generate`
   

2. If setup commands found, run installation:

   # Navigate to worktree
   cd .worktrees/${RUN_ID}-main
   
   # Check if dependencies already installed (handles resume)
   if [ ! -d node_modules ]; then
     echo "Installing dependencies..."
     {install-command}  # From CLAUDE.md (e.g., bun install)
   
     # Run postinstall if defined
     if [ -n "{postinstall-command}" ]; then
       echo "Running postinstall (codegen)..."
       {postinstall-command}  # From CLAUDE.md (e.g., npx prisma generate)
     fi
   else
     echo "Dependencies already installed"
   fi
   

3. If setup commands NOT found in CLAUDE.md:

   Error and instruct user:

   Setup Commands Required
   
   Worktrees need dependencies installed to run quality checks and codegen.
   
   Please add to your project's CLAUDE.md:
   
   ## Development Commands
   
   ### Setup
   
   - **install**: `bun install` (or npm install, pnpm install, etc.)
   - **postinstall**: `npx prisma generate` (optional - for codegen)
   
   Then re-run: /spectacular:spec {feature-description}
   

Announce: "Dependencies installed in worktree - ready for spec generation"

Step 1: Brainstorm Requirements

Context: All brainstorming happens in the context of the worktree (.worktrees/{runId}-main/)

Announce: "I'm brainstorming the design using Phases 1-3 (Understanding, Exploration, Design Presentation)."

Create TodoWrite checklist:

Brainstorming for Spec:
- [ ] Phase 1: Understanding (purpose, constraints, criteria)
- [ ] Phase 2: Exploration (2-3 approaches proposed)
- [ ] Phase 3: Design Presentation (design validated)
- [ ] Proceed to Step 2: Generate Specification

Phase 1: Understanding

Goal: Clarify scope, constraints, and success criteria.

1. Check current project state in working directory (note: we're in the worktree)
2. Read @docs/constitutions/current/ to understand constraints:
   • architecture.md - Layer boundaries
   • patterns.md - Mandatory patterns
   • tech-stack.md - Approved libraries
   • schema-rules.md - Database rules
3. Ask ONE question at a time to refine the idea
4. Use AskUserQuestion tool for multiple choice options
5. Gather: Purpose, constraints, success criteria

Constitution compliance:

• All architectural decisions must follow @docs/constitutions/current/architecture.md
• All pattern choices must follow @docs/constitutions/current/patterns.md
• All library selections must follow @docs/constitutions/current/tech-stack.md

Phase 2: Exploration

Goal: Propose and evaluate 2-3 architectural approaches.

1. Propose 2-3 different approaches that follow constitutional constraints
2. For each approach explain:
   • Core architecture (layers, patterns)
   • Trade-offs (complexity vs features)
   • Constitution compliance (which patterns used)
3. Use AskUserQuestion tool to present approaches as structured choices
4. Ask partner which approach resonates

Phase 3: Design Presentation

Goal: Present detailed design incrementally and validate.

1. Present design in 200-300 word sections
2. Cover: Architecture, components, data flow, error handling, testing
3. After each section ask: "Does this look right so far?" (open-ended)
4. Use open-ended questions for freeform feedback
5. Adjust design based on feedback

After Phase 3: Mark TodoWrite complete and proceed immediately to Step 2.

Step 2: Generate Specification

Announce: "Generating the specification document..."

Task:

• Feature: {feature-description}
• Design context: {summary from brainstorming}
• RUN_ID: {run-id from Step 0}
• Output location: .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/spec.md
• Constitution: All design decisions must follow @docs/constitutions/current/
• Analyze codebase for task-specific context:
  • Existing files to modify
  • New files to create (with exact paths per @docs/constitutions/current/architecture.md)
  • Dependencies needed (must be in @docs/constitutions/current/tech-stack.md)
  • Schema changes required (following @docs/constitutions/current/schema-rules.md)
• Follow all Iron Laws (see below):
  • Reference constitutions, don't duplicate
  • Link to SDK docs, don't embed examples
  • No implementation plans (that's /spectacular:plan's job)
  • Keep it lean (<300 lines)

Spec frontmatter must include:

---
runId: {run-id}
feature: {feature-slug}
created: {date}
status: draft
---

Use the Spec Structure template below to generate the document.

Step 2.5: Commit Spec to Worktree

After spec generation completes, commit the spec to the worktree branch:

cd .worktrees/${RUN_ID}-main
git add specs/
git commit -m "spec: add ${feature-slug} specification [${RUN_ID}]"

Announce: "Spec committed to {runId}-main branch in worktree"

Step 3: Architecture Quality Validation

CRITICAL: Before reporting completion, validate the spec against architecture quality standards.

Announce: "Validating spec against architecture quality standards..."

Read the generated spec and check against these dimensions:

3.1 Constitution Compliance

• Architecture: All components follow layer boundaries (@docs/constitutions/current/architecture.md)
  • Models - Services - Actions - UI (no layer violations)
  • Server/Client component boundaries respected
• Patterns: All mandatory patterns referenced (@docs/constitutions/current/patterns.md)
  • next-safe-action for server actions
  • ts-pattern for discriminated unions
  • Zod schemas for validation
  • routes.ts for navigation
• Schema: Database design follows rules (@docs/constitutions/current/schema-rules.md)
  • Proper indexing strategy
  • Naming conventions
  • Relationship patterns
• Tech Stack: All dependencies approved (@docs/constitutions/current/tech-stack.md)
  • No unapproved libraries
  • Correct versions specified
• Testing: Testing strategy defined (@docs/constitutions/current/testing.md)

3.2 Specification Quality (Iron Laws)

• No Duplication: Constitution rules referenced, not recreated
• No Code Examples: External docs linked, not embedded
• No Implementation Plans: Focus on WHAT/WHY, not HOW/WHEN
• Lean: Spec < 300 lines (if longer, likely duplicating constitutions)

3.3 Requirements Quality

• Completeness: All FRs and NFRs defined, no missing scenarios
• Clarity: All requirements unambiguous and specific (no "fast", "good", "better")
• Measurability: All requirements have testable acceptance criteria
• Consistency: No conflicts between sections
• Edge Cases: Boundary conditions and error handling addressed
• Dependencies: External dependencies and assumptions documented

3.4 Architecture Traceability

• File Paths: All new/modified files have exact paths per architecture.md
• Integration Points: How feature integrates with existing system clear
• Migration Impact: Schema changes and data migrations identified
• Security: Auth/authz requirements explicit

3.5 Surface Issues

If ANY checks fail, create .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/clarifications.md with:

# Clarifications Needed

## [Category: Constitution/Quality/Requirements/Architecture]

**Issue**: {What's wrong}
**Location**: {Spec section reference}
**Severity**: [BLOCKER/CRITICAL/MINOR]
**Question**: {What needs to be resolved}

Options:
- A: {Option with trade-offs}
- B: {Option with trade-offs}
- Custom: {User provides alternative}

Iteration limit: Maximum 3 validation cycles. If issues remain after 3 iterations, escalate to user with clarifications.md.

Step 4: Report Completion

IMPORTANT: After reporting completion, STOP HERE. Do not proceed to plan generation automatically. The user must review the spec and explicitly run /spectacular:plan when ready.

After validation passes OR clarifications documented, report to user:

If validation passed (single-repo mode):

Feature Specification Complete & Validated

RUN_ID: {run-id}
Worktree: .worktrees/{run-id}-main/
Branch: {run-id}-main
Location: .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/spec.md

Constitution Compliance: PASS
Architecture Quality: PASS
Requirements Quality: PASS

Note: Spec is in isolated worktree, main repo unchanged.

Next Steps (User Actions - DO NOT AUTO-EXECUTE):
1. Review the spec: .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/spec.md
2. When ready, create implementation plan: /spectacular:plan @.worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/spec.md

If validation passed (multi-repo mode):

Feature Specification Complete & Validated

RUN_ID: {run-id}
Workspace: {workspace-root}
Location: specs/{run-id}-{feature-slug}/spec.md

Repos affected:
- backend: @backend/docs/constitutions/current/
- frontend: @frontend/docs/constitutions/current/

Constitution Compliance: PASS
Architecture Quality: PASS
Requirements Quality: PASS

Note: Spec is at workspace root, affecting multiple repos.

Next Steps (User Actions - DO NOT AUTO-EXECUTE):
1. Review the spec: specs/{run-id}-{feature-slug}/spec.md
2. When ready, create plan: /spectacular:plan @specs/{run-id}-{feature-slug}/spec.md

If clarifications needed (single-repo mode):

Feature Specification Complete - Clarifications Needed

RUN_ID: {run-id}
Worktree: .worktrees/{run-id}-main/
Branch: {run-id}-main
Location: .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/spec.md
Clarifications: .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/clarifications.md

Note: Spec is in isolated worktree, main repo unchanged.

Next Steps:
1. Review spec: .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/spec.md
2. Answer clarifications: .worktrees/{run-id}-main/specs/{run-id}-{feature-slug}/clarifications.md
3. Once resolved, re-run: /spectacular:spec {feature-description}

If clarifications needed (multi-repo mode):

Feature Specification Complete - Clarifications Needed

RUN_ID: {run-id}
Workspace: {workspace-root}
Location: specs/{run-id}-{feature-slug}/spec.md
Clarifications: specs/{run-id}-{feature-slug}/clarifications.md

Repos affected:
- backend: @backend/docs/constitutions/current/
- frontend: @frontend/docs/constitutions/current/

Note: Spec is at workspace root, affecting multiple repos.

Next Steps:
1. Review spec: specs/{run-id}-{feature-slug}/spec.md
2. Answer clarifications: specs/{run-id}-{feature-slug}/clarifications.md
3. Once resolved, re-run: /spectacular:spec {feature-description}

---

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}

Multi-Repo Spec Template Addition

For multi-repo features, add this section to the spec:

## Constitutions

This feature must comply with constitutions from each affected repo:

**backend**: @backend/docs/constitutions/current/
- architecture.md - Backend layer boundaries
- patterns.md - Backend patterns (next-safe-action, etc.)
- schema-rules.md - Database design rules

**frontend**: @frontend/docs/constitutions/current/
- architecture.md - Frontend component structure
- patterns.md - Frontend patterns (React Query, etc.)

**shared-lib**: @shared-lib/docs/constitutions/current/
- (if applicable)

When brainstorming in multi-repo mode:

• Read constitutions from ALL relevant repos
• Note which repo each architectural decision applies to
• Ensure cross-repo consistency (e.g., API contracts)

Iron Laws

1. Reference, Don't Duplicate

NEVER recreate constitution rules in the spec

```markdown ## Layered Architecture

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

```markdown ### Zod Validation

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

```markdown ## Migration Plan

Phase 1: Database Schema

1. Create Prisma migration
2. Run migration
3. 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

```markdown ## Success Metrics

1. Adoption: 80% of users use feature within first month
2. Performance: Page loads in <500ms
3. 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.

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)

Error Handling

Worktree Creation Fails

• Check .worktrees/ is in .gitignore
• Run git worktree prune to clean stale entries
• Verify working directory is clean

Git-Spice Errors

• Run gs repo init to initialize repository
• Check gs ls to view current stack
• See using-git-spice skill for troubleshooting

Setup Commands Missing

• Project MUST define setup commands in CLAUDE.md
• See error message for required format
• Re-run spec command after adding commands

Validation Failures

• Maximum 3 iteration cycles
• If issues persist, escalate via clarifications.md
• Do not skip validation - it catches real problems

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.