Product Specs Writer

## 1. PRD Writing (prd)
**Impact:** CRITICAL
**Description:** Product Requirements Documents that align stakeholders on vision, scope, and success criteria. The foundation for all downstream specifications.

## 2. User Stories (stories)
**Impact:** CRITICAL
**Description:** User-centric requirements that capture who benefits, what they need, and why it matters. The bridge between business goals and engineering work.

## 3. Acceptance Criteria (criteria)
**Impact:** CRITICAL
**Description:** Testable conditions that define when a story is complete. The contract between PM, engineering, and QA.

## 4. Technical Specifications (technical)
**Impact:** HIGH
**Description:** Architecture decisions, system design, and implementation guidance. How the solution will be built.

## 5. API Specifications (api)
**Impact:** HIGH
**Description:** API contracts, request/response formats, versioning, and documentation. The interface between systems and teams.

## 6. Edge Cases & Error Handling (edge)
**Impact:** HIGH
**Description:** Failure modes, error states, and exception handling. What happens when things go wrong.

## 7. Design Handoff (design)
**Impact:** MEDIUM-HIGH
**Description:** Component specifications, interaction states, and responsive requirements. Translating designs to implementation.

## 8. Feature Flags & Rollout (rollout)
**Impact:** MEDIUM-HIGH
**Description:** Progressive rollout strategies, feature flags, experiments, and kill switches. Safe deployment patterns.

## 9. Success Metrics (metrics)
**Impact:** HIGH
**Description:** KPIs, measurement plans, and success criteria. How we know if we built the right thing.

## 10. Documentation Maintenance (maintenance)
**Impact:** MEDIUM
**Description:** Documentation lifecycle, versioning, deprecation, and update workflows. Keeping specs accurate over time.


---
title: API Specifications
impact: HIGH
tags: api, rest, openapi, documentation, contracts
---

## API Specifications

**Impact: HIGH**

API specs are contracts between services, teams, and external developers. Clear specs prevent integration bugs, reduce back-and-forth, and enable parallel development of frontend and backend.

### API Design Principles

1. **Consistency** — Same patterns across all endpoints
2. **Predictability** — Developers can guess behavior
3. **Discoverability** — Self-documenting responses
4. **Evolvability** — Can change without breaking clients
5. **Debuggability** — Errors help developers fix issues

### API Specification Components

| Component | Purpose | Required |
|-----------|---------|----------|
| **Endpoint** | URL path and HTTP method | Yes |
| **Description** | What this endpoint does | Yes |
| **Authentication** | Auth requirements | Yes |
| **Request** | Headers, params, body | Yes |
| **Response** | Success and error formats | Yes |
| **Examples** | Real request/response samples | Yes |
| **Rate Limits** | Throttling rules | If applicable |
| **Versioning** | API version info | Yes |

### Good API Spec Example (OpenAPI Style)

```yaml
# POST /workspaces/{workspace_id}/invitations
# Create a new workspace invitation

summary: Invite a user to a workspace
description: |
  Sends an invitation email to the specified address. The recipient
  can accept the invitation to join the workspace with the specified
  permission level. Invitations expire after 7 days.

  Requires Owner permission on the workspace.

tags:
  - Workspace Sharing

security:
  - BearerAuth: []

parameters:
  - name: workspace_id
    in: path
    required: true
    description: The unique identifier of the workspace
    schema:
      type: string
      format: uuid
    example: "550e8400-e29b-41d4-a716-446655440000"

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - email
          - permission_level
        properties:
          email:
            type: string
            format: email
            desc