writing-specs

What this skill does

# 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:

```bash
# 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.

```bash
# 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.

```bash
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**:
   ```bash
   # 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:
   ```markdown
   ## Development Commands

   ### Setup

   - **install**: `bun install`
   - **postinstall**: `npx prisma generate`
   ```

2. **If setup commands found, run installation**:

   ```bash
   # 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**:
   ```markdown
   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 feedba