Skip to content

SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist

documentation-specialist

Verified

This skill should be used when creating professional software documentation (SRS, PRD, OpenAPI, SDD, architecture docs, user manuals, tutorials, runbooks) from templates (greenfield) or reverse-engineering documentation from existing code like Spring Boot or FastAPI (brownfield). Also handles documentation audits/reviews, format conversion (Markdown, DOCX, PDF), and diagram generation (Mermaid first: C4, sequence, class, ER, state, flowchart; PlantUML Salt for UI wireframes and leftover UML). Use when asked to "create documentation", "document my code", "write SRS", "generate PRD", "write DESIGN_DOC.md", "architecture document", "wireframe", or "documentation specialist".

FileKindSize
SKILL.mdskill md10.0 KB
references/examples/TOC.mdmarkdown6.5 KB
references/examples/brownfield/database-failover-runbook.mdmarkdown8.1 KB
references/examples/brownfield/spring-boot-sdd.mdmarkdown5.6 KB
references/examples/greenfield/adr-microservices.mdmarkdown6.3 KB
references/examples/greenfield/architecture-doc.mdmarkdown3.7 KB
references/examples/greenfield/billing-srs.mdmarkdown12.4 KB
references/examples/greenfield/cli-getting-started.mdmarkdown9.3 KB
references/examples/greenfield/collaboration-prd.mdmarkdown13.8 KB
references/examples/greenfield/document-specialist-sdd.mdmarkdown15.4 KB
references/examples/greenfield/ecommerce-sdd.mdmarkdown7.8 KB
references/examples/greenfield/rest-api-tutorial.mdmarkdown13.8 KB
references/examples/greenfield/task-api-openapi.yamlconfig19.0 KB
references/examples/greenfield/taskmanager-user-manual.mdmarkdown8.7 KB
references/examples/greenfield/ui-wireframes.mdmarkdown5.8 KB
references/guides/requirements/README.mdmarkdown3.7 KB
references/mappings/backend/fastapi-mapping.yamlconfig9.7 KB
references/mappings/backend/spring-boot-mapping.yamlconfig24.1 KB
references/reference/01-philosophy.mdmarkdown2.0 KB
references/reference/02-requirements-srs-vs-prd.mdmarkdown1.2 KB
references/reference/02-requirements-traceability.mdmarkdown1.7 KB
references/reference/02-requirements-writing.mdmarkdown1.4 KB
references/reference/03-design-adrs.mdmarkdown2.2 KB
references/reference/03-design-arc42.mdmarkdown2.6 KB
references/reference/03-design-requirements-matrix.mdmarkdown1.3 KB
references/reference/04-diagrams-c4-hierarchy.mdmarkdown2.0 KB
references/reference/04-diagrams-selection.mdmarkdown5.1 KB
references/reference/04-diagrams-state-vs-activity.mdmarkdown2.3 KB
references/reference/05-api-checklist.mdmarkdown2.0 KB
references/reference/05-api-openapi.mdmarkdown3.4 KB
references/reference/05-api-stripe-gold-standard.mdmarkdown1.8 KB
references/reference/06-deployment-diagrams.mdmarkdown1.8 KB
references/reference/06-deployment-documentation.mdmarkdown2.9 KB
references/reference/06-deployment-runbooks.mdmarkdown2.5 KB
references/reference/06-operational-docs.mdmarkdown2.7 KB
references/reference/07-user-kb-approach.mdmarkdown1.8 KB
references/reference/07-user-kb-template.mdmarkdown3.1 KB
references/reference/07-user-writing-style.mdmarkdown2.0 KB
references/reference/08-agile-process.mdmarkdown3.2 KB
references/reference/08-tutorial-writing.mdmarkdown7.4 KB
references/reference/09-code-to-docs-detection.mdmarkdown2.5 KB
references/reference/09-code-to-docs-example.mdmarkdown3.2 KB
references/reference/09-code-to-docs-when.mdmarkdown1.7 KB
references/reference/09-code-to-docs-workflow.mdmarkdown2.0 KB
references/reference/10-quality-bonsai-pruning.mdmarkdown2.4 KB
references/reference/10-quality-checklist.mdmarkdown2.6 KB
references/reference/10-quality-metrics.mdmarkdown3.1 KB
references/reference/11-voice-and-style.mdmarkdown1.5 KB
references/reference/comprehensive-guide.mdmarkdown7.3 KB
references/templates/markdown/DESIGN_DOC.mdmarkdown4.5 KB
references/templates/markdown/api-openapi.yamlconfig17.7 KB
references/templates/markdown/architecture.mdmarkdown1.6 KB
references/templates/markdown/design-sdd.mdmarkdown143 B
references/templates/markdown/developer-tutorial.mdmarkdown7.1 KB
references/templates/markdown/getting-started.mdmarkdown6.5 KB
references/templates/markdown/howto-guide.mdmarkdown4.1 KB
references/templates/markdown/requirements-prd.mdmarkdown10.2 KB
references/templates/markdown/requirements-srs.mdmarkdown17.0 KB
references/templates/markdown/runbook.mdmarkdown8.8 KB
references/templates/markdown/user-manual.mdmarkdown4.8 KB
references/workflows/TOC.mdmarkdown1.9 KB
references/workflows/audit-workflow.mdmarkdown2.5 KB
references/workflows/brownfield-workflow.mdmarkdown3.6 KB
references/workflows/brownfield/fastapi-guide.mdmarkdown1.8 KB
references/workflows/brownfield/pulumi-guide.mdmarkdown1.9 KB
references/workflows/brownfield/springboot-guide.mdmarkdown2.2 KB
references/workflows/convert-workflow.mdmarkdown1.4 KB
references/workflows/design-workflow.mdmarkdown3.0 KB
references/workflows/diagram-workflow.mdmarkdown3.7 KB
references/workflows/greenfield-workflow.mdmarkdown3.4 KB
references/workflows/greenfield/advanced.mdmarkdown1.9 KB
references/workflows/greenfield/openapi-guide.mdmarkdown2.5 KB
references/workflows/greenfield/prd-guide.mdmarkdown2.0 KB
references/workflows/greenfield/srs-guide.mdmarkdown2.0 KB
references/workflows/runbook-workflow.mdmarkdown2.4 KB
references/workflows/tutorial-workflow.mdmarkdown2.3 KB
references/workflows/user-docs-workflow.mdmarkdown2.3 KB

references/examples/greenfield/collaboration-prd.md

View on GitHub
# Product Requirements Document: Real-Time Collaboration Platform

---
**Document ID**: PRD-COLLAB-001
**Version**: 1.2.0
**Date**: 2025-01-15
**Owner**: Product Management Team
**Contributors**: Engineering, Design, Customer Success
**Status**: In Development

TOKEN_BUDGET: 1000
TIER: 3 (Example)
LOAD_TRIGGER: Few-shot example for PRD creation
---

## Objective

Build a **real-time collaboration platform** that enables distributed teams to work together seamlessly through shared workspaces, live document editing, video conferencing, and integrated task management.

**Problem**: Remote teams struggle with fragmented tools (Slack for chat, Google Docs for documents, Zoom for video, Asana for tasks), leading to context switching and reduced productivity.

**Solution**: An all-in-one platform that combines communication, collaboration, and coordination in a unified workspace.

---

## Success Metrics

### Primary Metrics

| Metric | Target | Measurement |
|--------|--------|-------------|
| **Weekly Active Users (WAU)** | 10,000 | Users who interact with platform ≥1x/week |
| **Daily Active Workspaces** | 2,500 | Workspaces with ≥1 active session/day |
| **Collaboration Sessions** | 5,000/week | Real-time editing or video sessions |
| **User Retention (30-day)** | 65% | Users active in month 2 after signup |

### Secondary Metrics

| Metric | Target | Measurement |
|--------|--------|-------------|
| **Average Session Duration** | 25 minutes | Time from login to logout |
| **Documents Created** | 20,000/month | New documents, whiteboards, tasks |
| **Video Call Participation** | 40% of users | Users who join ≥1 video call/week |
| **Task Completion Rate** | 75% | Tasks marked done / tasks created |

---

## User Personas

### 1. Remote Worker (Sarah)
- **Role**: Marketing Manager
- **Goals**: Collaborate on campaigns, share feedback on documents
- **Pain Points**: Too many tools, hard to find latest version of docs
- **Tech Savviness**: Medium
- **Frequency**: Daily (2-4 hours)

### 2. Engineering Lead (Marcus)
- **Role**: Software Engineering Manager
- **Goals**: Track sprint tasks, review design docs, conduct standups
- **Pain Points**: Context switching between Jira, Confluence, Zoom
- **Tech Savviness**: High
- **Frequency**: Daily (6-8 hours)

### 3. Freelance Designer (Alex)
- **Role**: UI/UX Designer
- **Goals**: Present designs, gather feedback, iterate quickly
- **Pain Points**: Email attachments outdated, hard to track feedback
- **Tech Savviness**: Medium-High
- **Frequency**: 3-4 times/week (2-3 hours)

---

## User Stories

### Epic 1: Workspace Management

**US-001**: As a team lead, I want to create a workspace for my team, so that we have a centralized hub for collaboration.
- **Acceptance Criteria**:
  - Given I'm logged in
  - When I click "Create Workspace"
  - Then I can name the workspace, add team members, and set permissions
  - And the workspace appears in my sidebar

**US-002**: As a workspace admin, I want to invite team members via email, so they can join our workspace.
- **Acceptance Criteria**:
  - Given I'm a workspace admin
  - When I enter email addresses and click "Invite"
  - Then invitees receive an email with a join link
  - And they can create an account or log in to join

---

### Epic 2: Real-Time Document Editing

**US-010**: As a remote worker, I want to edit documents simultaneously with teammates, so we can collaborate in real-time.
- **Acceptance Criteria**:
  - Given multiple users open the same document
  - When user A types text
  - Then user B sees the changes within 500ms
  - And cursor positions and selections are visible to all users

**US-011**: As a document creator, I want to see who's currently viewing or editing my document, so I know who's active.
- **Acceptance Criteria**:
  - Given a document is open
  - When other users join
  - Then I see their avatars and names in the top-right corner
  - And their cursor positions are highlighted with their color

**US-012**: As a collaborator, I want to comment on specific sections of a document, so I can provide feedback without editing.
- **Acceptance Criteria**:
  - Given I highlight text
  - When I click "Comment"
  - Then a comment thread appears in the margin
  - And other users receive a notification
  - And I can @mention specific teammates

---

### Epic 3: Video Conferencing

**US-020**: As a remote worker, I want to start instant video calls with my team, so we can discuss issues synchronously.
- **Acceptance Criteria**:
  - Given I'm in a workspace
  - When I click "Start Call"
  - Then a video call room opens
  - And team members receive a notification
  - And they can join with 1 click (no separate app)

**US-021**: As a meeting participant, I want to share my screen during video calls, so I can present slides or demos.
- **Acceptance Criteria**:
  - Given I'm in a video call
  - When I click "Share Screen"
  - Then I can select a window or entire screen to share
  - And other participants see my screen in real-time
  - And I can annotate (draw, highlight) on the shared screen

**US-022**: As a call host, I want to record video calls, so absent teammates can watch later.
- **Acceptance Criteria**:
  - Given I start a video call
  - When I click "Record"
  - Then the call is recorded (video + audio)
  - And a recording file is saved to the workspace
  - And participants see a "Recording" indicator

---

### Epic 4: Task Management

**US-030**: As a project manager, I want to create tasks and assign them to team members, so work is organized and tracked.
- **Acceptance Criteria**:
  - Given I'm in a workspace
  - When I create a task with title, description, assignee, due date
  - Then the task appears in the assignee's task list
  - And they receive a notification

**US-031**: As a team member, I want to see my tasks in a Kanban board view, so I can visualize my workflow.
- **Acceptance Criteria**:
  - Given I have assigned tasks
  - When I open the Tasks view
  - Then I see columns: To Do, In Progress, In Review, Done
  - And I can drag-and-drop tasks between columns
  - And task counts update in real-time

**US-032**: As a task assignee, I want to update task status and add comments, so I can track progress.
- **Acceptance Criteria**:
  - Given I'm assigned a task
  - When I change status to "In Progress"
  - Then the task moves to the In Progress column
  - And I can add comments or attach files
  - And watchers receive notifications

---

## Features and Requirements

### Feature 1: Shared Workspaces

**Description**: Team hubs containing documents, tasks, files, and chat channels.

**Requirements**:
- **REQ-WS-001**: Users can create unlimited workspaces (free tier: 1, paid tier: unlimited)
- **REQ-WS-002**: Workspace members see a unified sidebar with: Documents, Tasks, Files, Channels
- **REQ-WS-003**: Workspaces support role-based permissions: Owner, Admin, Member, Guest
- **REQ-WS-004**: Workspace search: Find documents, tasks, messages across entire workspace

**Priority**: Must-Have
**Effort**: 3 sprints

---

### Feature 2: Real-Time Collaborative Editor

**Description**: Google Docs-like editor with live cursors, comments, and version history.

**Requirements**:
- **REQ-EDIT-001**: Rich text editor: Bold, italic, headings, lists, links, images
- **REQ-EDIT-002**: Live collaboration: See teammates' cursors and edits in real-time (<500ms latency)
- **REQ-EDIT-003**: Comments and mentions: @mention teammates, resolve comment threads
- **REQ-EDIT-004**: Version history: View and restore previous document versions
- **REQ-EDIT-005**: Offline mode: Edit offline, sync changes when reconnected

**Priority**: Must-Have
**Effort**: 4 sprints

**Technical Considerations**:
- Use **Operational Transformation (OT)** or **CRDTs** for conflict-free editing
- WebSocket for real-time sync
- PostgreSQL + Redis for state management

---

### Feature 3: Integrated Video Conferencing

**Description**: Native video calls without leaving the platform.

**Requirements**:
- **REQ-VIDEO-001**: Support 1:1 and group calls (up to 50 participants)
- **REQ-VIDEO-002**: Screen sharing with annotations (draw, highlight)
- **REQ-VIDEO-003**: Call recording (host-initiated, stored in workspace)
- **REQ-VIDEO-004**: Background blur and virtual backgrounds
- **REQ-VIDEO-005**: Breakout rooms (split large calls into smaller groups)

**Priority**: Must-Have
**Effort**: 5 sprints

**Technical Considerations**:
- Use **WebRTC** for peer-to-peer video
- SFU (Selective Forwarding Unit) for calls >10 participants
- Third-party option: Integrate with Twilio Video or Agora.io

---

### Feature 4: Task and Project Management

**Description**: Lightweight task management with Kanban boards.

**Requirements**:
- **REQ-TASK-001**: Create tasks with title, description, assignee, due date, labels
- **REQ-TASK-002**: Kanban board view with drag-and-drop
- **REQ-TASK-003**: Task dependencies (Task B blocks Task A)
- **REQ-TASK-004**: Recurring tasks (daily, weekly, monthly)
- **REQ-TASK-005**: Task templates (common workflows)

**Priority**: Should-Have
**Effort**: 3 sprints

---

### Feature 5: File Storage and Sharing

**Description**: Centralized file repository with version control.

**Requirements**:
- **REQ-FILE-001**: Upload files: Drag-and-drop or file picker
- **REQ-FILE-002**: File previews: Images, PDFs, videos (in-browser)
- **REQ-FILE-003**: Version control: Track file updates, restore previous versions
- **REQ-FILE-004**: File permissions: Public (workspace), restricted (specific members)
- **REQ-FILE-005**: Storage quotas: Free tier 5GB, Pro tier 100GB, Enterprise unlimited

**Priority**: Must-Have
**Effort**: 2 sprints

---

## Out of Scope (v1.0)

**Explicitly NOT included in the initial release**:

- ❌ Mobile apps (iOS, Android) - Web-first, mobile in v2.0
- ❌ Custom integrations (Jira, GitHub) - v1.5
- ❌ Advanced analytics (usage dashboards, heatmaps) - v2.0
- ❌ White-labeling or custom branding - Enterprise feature, v2.5
- ❌ On-premise deployment - Cloud-only for v1.0
- ❌ End-to-end encryption (E2EE) - Roadmap for v2.0

---

## User Journey

### Journey 1: First-Time User Onboarding

1. **Sign up**: Email + password or Google OAuth
2. **Create workspace**: Name workspace, skip team invites for now
3. **Welcome tour**: Guided walkthrough (Documents, Tasks, Video)
4. **Create first document**: Start typing immediately
5. **Invite teammate**: Send invite via email
6. **Collaborate**: Edit document together in real-time

**Success criteria**: User completes onboarding and invites ≥1 teammate within 10 minutes.

---

### Journey 2: Daily Team Collaboration

1. **Log in**: Open workspace from sidebar
2. **Check tasks**: Review Kanban board, move tasks to "In Progress"
3. **Join standup call**: Click notification, join video call
4. **Share screen**: Show design mockups, gather feedback
5. **Update document**: Edit spec doc, @mention designer for review
6. **End day**: Mark tasks complete, schedule tomorrow's tasks

**Success criteria**: User completes ≥3 collaborative activities (edit doc, video call, task update) per session.

---

## Technical Architecture (High-Level)

### Frontend
- **Framework**: React 18 + TypeScript
- **State Management**: Zustand or Redux Toolkit
- **Real-Time**: Socket.io client
- **Editor**: ProseMirror or Slate.js
- **Video**: WebRTC + adapter.js

### Backend
- **API**: Node.js + Express.js (REST + WebSocket)
- **Database**: PostgreSQL (relational data), Redis (cache, pub/sub)
- **File Storage**: AWS S3 or Cloudflare R2
- **Video**: Twilio Video API or self-hosted SFU (mediasoup)
- **Auth**: JWT + OAuth 2.0 (Google, GitHub)

### Infrastructure
- **Hosting**: AWS (EC2, RDS, S3, CloudFront)
- **CI/CD**: GitHub Actions
- **Monitoring**: Datadog or Grafana + Prometheus

---

## Wireframes and Mockups

**Link to Figma**: [Collaboration Platform Designs](https://figma.com/workspace-designs)

**Key Screens**:
- Workspace home (sidebar + main area)
- Document editor (real-time collaboration)
- Video call interface (grid view, screen share)
- Kanban task board (drag-and-drop)

---

## Open Questions

1. **File storage limits**: Should we enforce per-file size limits (e.g., max 100MB per file)?
   - **Decision needed by**: 2025-01-20
   - **Owner**: Engineering Lead

2. **Video quality settings**: Auto-adjust based on bandwidth or let users choose (low, medium, high)?
   - **Decision needed by**: 2025-01-25
   - **Owner**: Product Manager

3. **Pricing tiers**: What features should be free vs. paid?
   - **Decision needed by**: 2025-02-01
   - **Owner**: Product + Business Development

---

## Dependencies

- **External APIs**: Twilio Video API (video calls)
- **Design assets**: Finalize UI designs by 2025-01-25
- **Infrastructure**: AWS account provisioning by 2025-01-30

---

## Risks and Mitigation

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| Real-time sync conflicts (OT algorithm complexity) | High | Medium | Use battle-tested library (Yjs, ShareDB) |
| Video call quality issues (network latency) | Medium | High | Implement bandwidth detection, adaptive quality |
| Scaling costs (video + storage) | High | Medium | Start with 3rd-party APIs, optimize in v2.0 |
| Competitor launches similar product | Medium | Low | Focus on superior UX, faster iteration |

---

## Timeline and Milestones

| Milestone | Target Date | Deliverables |
|-----------|-------------|--------------|
| **Alpha** | 2025-03-01 | Core features working, internal testing |
| **Beta** | 2025-04-15 | Invite-only beta with 100 users |
| **Public Launch** | 2025-06-01 | Public release, marketing campaign |
| **v1.1** | 2025-08-01 | Mobile web optimization, integrations |

---

## Approval and Sign-Off

| Role | Name | Signature | Date |
|------|------|-----------|------|
| **Product Manager** | Jane Doe | ✅ Approved | 2025-01-15 |
| **Engineering Lead** | Marcus Chen | ✅ Approved | 2025-01-15 |
| **Design Lead** | Sarah Kim | ✅ Approved | 2025-01-15 |
| **Stakeholder** | John Smith (CEO) | ⏳ Pending | - |

---

**End of PRD Example - Real-Time Collaboration Platform**
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall