spec-manager

What this skill does

# spec-manager Skill

This skill writes and displays the application's specification documents. It is used before implementation, before adding new features, or when design changes are made, to update the documents and notify users.

## 🚨 Critical Rules

**NEVER write spec/design/architecture documents to ANY location except `.spec-manager/`**

- NEVER create `docs/`, `specifications/`, `design/` directories for spec content before `.spec-manager/` exists
- NEVER write PRD.md, TechStack.md, design docs, architecture docs to any location except `.spec-manager/`
- ALWAYS invoke this skill FIRST for ANY specification-related documentation
- Other documentation (README, API reference, user guides) allowed ONLY AFTER `.spec-manager/` is complete

**Auto-invoke triggers (expanded):**

- Writing spec/design/architecture/requirements documents (any directory, any filename)
- Creating PRD, tech spec, design doc, architecture doc (any location)
- User creation requests ("I want to create XX" with/without URL)
- Starting implementation of new features
- Completing significant changes (3+ files modified)
- Major refactoring or architectural changes
- Keywords: specifications/spec/specification/design/architecture/requirements/PRD/document
- Session end with specification changes

## Standard Workflow

**0. FIRST:** Verify `.spec-manager/` exists and is current. If not, run this skill before any other documentation.

**1. Delegate to specialized skills (if available):**

- Check if specialized planning skills exist
- Record TODO to return to spec-manager after planning
- Delegate planning to specialized skill
- Return here to write specification documents

**2. Interactive clarification (if requirements unclear):**

- Use `AskUserQuestion` tool with numbered options
- Ask one question at a time
- Build specifications incrementally

**3. Write/update specifications:**

- Write to `.spec-manager/` directory ONLY via this skill
- Notify user of updates

**4. AFTER step 3:** Other documentation (README, etc.) can be created if needed

**Question format:** Always provide numbered options (1, 2, 3..., 1-1, 1-2,...) when asking specification questions.

## Dual Purpose: Specification Writing AND Requirements Clarification

This skill serves two primary functions:

### 1. Delegating to Specialized Planning Skills (Priority)

**When to delegate**: If other specialized skills for planning specifications are available in the system (e.g., `langgraph-master`, `business-panel`, domain-specific planning skills), delegate the planning process to them first.

**Workflow**:

1. Detect that specifications need to be created or updated
2. Check if specialized planning skills are available
3. If available:
   - **Record a TODO** using `TodoWrite` to return to `spec-manager` skill after planning completes
   - Example TODO: "Return to spec-manager to write specification documents after planning"
   - Invoke the appropriate specialized skill for planning
4. Wait for planning completion (the TODO ensures we don't forget to return)
5. Return to this skill to write the specification documents based on the planning output
6. Mark the TODO as completed
7. Update `.spec-manager/` directory with the specifications

**Example**: If planning a LangGraph application, delegate to `langgraph-master` skill for architectural planning, then return here to write the formal specification documents.

### 2. Interactive Requirements Clarification (When No Specialized Skills)

**When to use**: If no specialized planning skills are available, OR if the user's requirements are unclear or ambiguous even after initial analysis.

**Workflow**:

1. Detect that specifications are unclear or incomplete
2. Automatically invoke this skill's interactive questioning mode
3. Use `AskUserQuestion` tool to ask **one question at a time**
4. Provide **clear options** for users to select from (when possible)
5. Build specifications incrementally based on user's answers
6. After gathering sufficient information, synthesize and confirm with user
7. Write the specification documents to `.spec-manager/` directory

**Example**: User says "I want to create a web app" without details → This skill automatically starts asking:

- "What type of web application?" [E-commerce, Blog, Dashboard, Social network]
- "Who are the target users?" [General public, Business users, Internal team]
- Continue with technical stack, features, architecture, etc.

See the **"Clarifying Unclear Specifications"** section below for detailed questioning methodology.

## Proactive Usage Guidelines

**IMPORTANT**: This skill should be invoked **automatically and proactively** by Claude without waiting for explicit user requests.

### How to Invoke Proactively

When conditions are met, Claude should:

1. **Detect the trigger condition** (e.g., completed 5 file changes for new auth feature)
2. **Automatically invoke this skill** without asking for permission first
3. **Update specification documents** in `.spec-manager/` directory
4. **Notify the user** with a summary like:
   ```
   📝 Specification documents have been automatically updated:
   - PRD.md: Added authentication feature requirements
   - TechStack.md: Updated with JWT library dependencies
   - FileStructure.md: Reflected new auth/ directory structure
   ```

### What NOT to Do

❌ **Don't wait** for explicit `/update-spec` command after every change
❌ **Don't ask** "Should I update the specifications?" - just do it proactively
❌ **Don't ignore** completed implementations - always sync specifications
❌ **Don't skip** specification updates when user is focused on coding

### Integration with Development Workflow

```
Development Flow:
1. User requests feature → Invoke spec-manager (initialize/review specs)
2. Implement feature → Track changes
3. Complete implementation → Invoke spec-manager (auto-update specs)
4. Mark task complete → Specifications already synchronized ✅
```

### Clarifying Unclear Specifications

When the user's requirements or specifications are unclear or incomplete, use an **interactive questioning approach** to systematically gather information:

#### Process for Specification Clarification

1. **Identify Gaps**: Determine what information is missing or ambiguous

   - Product requirements unclear?
   - Technical stack not specified?
   - User flows undefined?
   - Architecture decisions needed?

2. **Ask One Question at a Time**: Use the `AskUserQuestion` tool to gather information progressively

   - **DO NOT** ask multiple complex questions simultaneously
   - Focus on one aspect at a time for clarity
   - Provide concrete options when possible

3. **Provide Clear Options**: Give users specific choices to select from

   - Example options for architecture: "Monolith", "Microservices", "Serverless"
   - Example options for database: "PostgreSQL", "MongoDB", "SQLite"
   - Always include descriptions explaining each option's trade-offs

4. **Build Incrementally**: Use each answer to inform the next question

   - Start with high-level decisions (purpose, target users, core features)
   - Move to technical choices (stack, architecture, database)
   - Finally address implementation details (deployment, testing, monitoring)

5. **Synthesize and Confirm**: After gathering information, summarize and confirm
   - Present the collected requirements back to the user
   - Ask for confirmation before writing specification documents
   - Allow the user to correct or refine any points

#### Example Question Flow

```
Question 1: "What is the primary purpose of this application?"
Options: ["E-commerce platform", "Content management system", "Data analytics dashboard", "Social network"]

↓ User selects "E-commerce platform"

Question 2: "Who are the target users?"
Options: ["B2C consumers", "B2B businesses", "Internal company use", "Multi-tenant SaaS"]

↓ User selects "B2C consumers"

Question 3: "What are the core features needed for launch?"
Options: [Allow multiple selections: "Prod