---
name: spec-writer
description: Generate Product Requirements Document with EARS syntax and structured ambiguity clarification
triggers: [spec, PRD, feature, requirements, product requirements, write spec, new feature]
tags: [product]
context_cost: medium
---
# Spec Writer Skill

## Goal
Transform a user goal or feature request into a structured PRD using EARS syntax. Before generating requirements, invoke the ambiguity layer to clarify unclear aspects. Human approval required before proceeding to implementation.

## Steps

1. **Receive and understand the goal**
   - First, check for `Step 0` strategic context in `docs/strategic/` (e.g., `BUSINESS_CASE.md`, `EMPATHY_MAP.md`, `PROBLEM_STATEMENT.md`). If present, read them.
   - Ask the user: "Describe what you want to build in plain language"
   - Identify: Who is the user? What problem does it solve? What does success look like? (using the strategic docs if available)

2. **Ambiguity Layer — ask clarifying questions**
   Identify and ask about ALL ambiguous aspects before writing requirements:
   ```
   Questions to ask (examples):
   - "Who are the users of this feature? (roles, permissions, guest vs authenticated)"
   - "What happens if [edge case] occurs?"
   - "What are the performance expectations? (response time, concurrent users)"
   - "Is there an existing system this integrates with? What are its constraints?"
   - "What is explicitly out of scope for this version?"
   - "Are there any regulatory requirements? (GDPR, HIPAA, PCI-DSS)"
   - "What devices/browsers must be supported?"
   ```
   Wait for answers before proceeding.

3. **Generate the PRD** using templates/product/PRD_TEMPLATE.md

4. **Write EARS requirements** — use all 5 patterns as appropriate:

   **Ubiquitous** (always applies):
   ```
   THE SYSTEM SHALL encrypt all data in transit using TLS 1.3 or higher.
   ```

   **Event-Driven** (triggered by an event):
   ```
   WHEN a user submits a login form with incorrect credentials 3 consecutive times
   THE SYSTEM SHALL lock the account for 15 minutes and send an email notification.
   ```

   **State-Driven** (while in a state):
   ```
   WHILE the payment processing service is unavailable
   THE SYSTEM SHALL queue requests and retry with exponential backoff up to 3 times.
   ```

   **Optional Feature** (feature flag / conditional):
   ```
   WHERE two-factor authentication is enabled for the account
   THE SYSTEM SHALL require a TOTP code on each login attempt.
   ```

   **Unwanted Behavior** (negative requirements):
   ```
   THE SYSTEM SHALL NOT store plaintext passwords in any medium.
   THE SYSTEM SHALL NOT expose internal stack traces in HTTP responses.
   ```

5. **Write acceptance criteria**
   Each requirement needs 1+ verifiable acceptance criteria:
   ```
   Given [precondition]
   When [action]
   Then [expected outcome with measurable result]
   ```

6. **Non-functional requirements**
   Always include:
   - Performance: expected response time, throughput
   - Security: data classification, access control requirements
   - Accessibility: WCAG level (if UI feature)
   - Scalability: expected load, growth projections

7. **Out of scope section**
   Explicitly list what this feature does NOT include. This prevents scope creep.

8. **Present PRD to human for approval**
   Say: "Here is the PRD. Please review and approve before I proceed to architecture/planning."

9. **After approval: create SDLC checkpoint S01**
   - Invoke sdlc-checkpoint.skill → creates SESSION_SNAPSHOT/S01_requirements.md
   - Updates PROJECT_STATE.md → current phase: S02_DESIGN

## Constraints
- NEVER skip the ambiguity layer — unresolved ambiguity is the #1 cause of rework
- NEVER start planning or implementation without human approval of the PRD
- All requirements must be EARS-formatted and verifiable (not vague like "fast" or "user-friendly")
- Use the PRD template in templates/product/PRD_TEMPLATE.md

## Output Format
Completed PRD.md file at project root (or docs/) using templates/product/PRD_TEMPLATE.md structure.

## Security & Guardrails

### 1. Skill Security (Spec Writer)
- **Mandatory Threat Modeling**: The agent must intrinsically embed a lightweight threat model into the PRD generation process. If the feature involves PII, financial transactions, or external system integration, the agent must refuse to generate the final PRD until a Security NFR explicitly addresses Data-in-Transit and Data-at-Rest.
- **Strict NFR Templating**: The agent is barred from inventing subjective Non-Functional Requirements (e.g., "The system must be secure from hackers"). All security NFRs must map to verifiable industry standards (e.g., "The system shall comply with OWASP ASVS Level 2").

### 2. System Integration Security
- **Explicit Out-of-Scope Privileges**: The "Out of Scope" section must explicitly name prohibited downstream integrations or data flows. If building a caching service, it must explicitly state "This service SHALL NOT have long-term administrative database access."
- **Data Classification Anchoring**: Every PRD must start with a Data Classification directive (Public, Internal, Confidential, Restricted). The agent must use this anchor to determine the baseline cryptographic and authorization EARS requirements needed for the document.

### 3. LLM & Agent Guardrails
- **Requirement Sanitization**: The agent must scrub any user prompt inputs that attempt to explicitly define hardcoded passwords, developer backdoor accounts, or disabled SSL verifications before converting them into EARS requirements.
- **Prompt Fatigue Vulnerability**: A user might attempt to exhaust the agent's "Ambiguity Layer" by giving rapid, nonsensical answers. The agent must enforce a threshold (e.g., 3 failed clarification attempts) and cleanly abort the PRD generation rather than outputting a compromised or hallucinated specification.