SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist
documentation-specialist
VerifiedThis 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".
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**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |