Specify with Requirements

Skill Info

Part of the spec-manager agent. This skill analyzes requirements and generates detailed technical specifications.

Input

The user provides a task slug (or task title) as arguments: $ARGUMENTS

If no arguments are provided:

1. List all */requirements.md files in specs/ directory
2. Ask the user which one to process

If a task title (not slug) is provided, convert it to a slug to find the matching files.

Process

Step 1: Locate and Read Requirements

1. Find specs/{slug}/requirements.md
2. If the file doesn't exist, inform the user and suggest running /init-specs first
3. Read the full requirements document

Step 2: Validate Requirements Completeness

Check that requirements are sufficiently detailed:

• Overview section is filled in
• At least one functional requirement is defined
• Acceptance criteria exist

If requirements are incomplete or too vague, inform the user about what's missing and ask them to fill in the gaps before proceeding. Do NOT generate specs from empty templates.

Step 3: Analyze Requirements

Perform thorough analysis of the requirements:

1. Decompose each functional requirement into technical components
2. Identify implicit requirements not explicitly stated
3. Map requirements to technical decisions (data models, APIs, algorithms)
4. Detect conflicts or ambiguities between requirements
5. Assess technical feasibility and complexity
6. Examine the existing codebase for related code, patterns, and conventions

Step 4: Clarify if Needed

If analysis reveals ambiguities, conflicts, or gaps:

1. Present findings to the user with specific questions
2. Use AskUserQuestion tool for structured choices when applicable
3. Wait for user responses before finalizing specs
4. Iterate until all open questions are resolved

Example clarifications:

• "FR-1 mentions 'real-time updates' but doesn't specify the mechanism. Should we use WebSocket, SSE, or polling?"
• "FR-2 and FR-3 seem to conflict regarding data access. Which takes priority?"
• "The performance requirement of '<100ms response time' may conflict with the data aggregation in FR-4. Should we add caching?"

Step 5: Generate Specs

Update specs/{slug}/specs.md with comprehensive technical specifications:

# Specs: {Original Task Title}

> Created: {original date}
> Updated: {YYYY-MM-DD}
> Status: Draft
> Requirements: [requirements.md](./requirements.md)

## Overview

{Brief technical overview of what will be built, derived from requirements}

## Technical Specifications

### TS-1: {Spec Name} (from FR-1)

- **Description**: {Technical description}
- **Components Involved**: {List of components/modules}
- **Data Flow**: {How data moves through the system}
- **Implementation Approach**: {High-level approach}
- **Constraints**: {Technical constraints}

### TS-2: {Spec Name} (from FR-2)

{Same structure}

## Architecture

### Component Design

{Describe the components that need to be created or modified}

### Data Flow

{Describe how data flows through the system for this feature}

### Integration Points

{How this feature integrates with existing systems}

## Data Models

### {Model Name}

| Field | Type | Description | Constraints |
|-------|------|-------------|-------------|
|       |      |             |             |

## API / Interface Design

### {Endpoint/Function Name}

- **Method**: {GET/POST/etc. or function signature}
- **Path**: {URL path or module path}
- **Input**: {Request body/parameters}
- **Output**: {Response format}
- **Errors**: {Possible error responses}

## Error Handling

| Scenario | Handling Strategy | User Impact |
|----------|-------------------|-------------|
|          |                   |             |

## Dependencies

### External
- {Library/service}: {Purpose} - {Version/notes}

### Internal
- {Module/component}: {How it's used}

## Security Considerations

- {Security concern and mitigation}

## Performance Considerations

- {Performance concern and mitigation}

## Open Questions

- {Any remaining unresolved questions}

## Clarification Log

| # | Question | Answer | Date |
|---|----------|--------|------|
| 1 | {Question asked} | {Answer received} | {Date} |

Step 6: Report and Request Review

After generating specs, display a summary:

Specs generated for: "{Original Task Title}"

Updated: specs/{slug}/specs.md

Summary:
  - {N} technical specifications derived from {M} requirements
  - {X} components identified
  - {Y} API endpoints/interfaces defined
  - {Z} open questions remaining

Please review the generated specs in specs/{slug}/specs.md

If you need to clarify or modify anything, discuss it here.
When specs are finalized, run:
  /plan-with-specs {slug}

Clarification Cycle

If the user requests changes or has questions about the generated specs:

1. Read the current specs file
2. Discuss the user's concerns
3. Update the specs document with agreed changes
4. Log the clarification in the "Clarification Log" table
5. Update the "Updated" date
6. Repeat until the user is satisfied

Requirement Changes

If the user requests changes to requirements during this process:

1. Update specs/{slug}/requirements.md with the changes
2. Re-analyze all requirements (not just the changed ones)
3. Regenerate specs/{slug}/specs.md reflecting the changes
4. Note the requirement change in the Clarification Log
5. Reset specs/{slug}/plans.md status to "Pending (specs updated)"

Important

• Always read the requirements file before generating specs - never guess
• Examine the existing codebase for patterns, conventions, and related code
• Specs must be traceable back to requirements (use FR-X references)
• Flag any requirements that are technically infeasible or very costly
• Include a clarification log for audit trail
• Do not proceed to plan generation - wait for user to run /plan-with-specs