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/templates/markdown/requirements-prd.md
View on GitHub# Product Requirements Document (PRD)
**Product**: [Product Name]
**Feature/Epic**: [Feature Name]
**Status**: 🟡 Draft | 🔵 In Review | 🟢 Approved
**Author**: [Your Name]
**Created**: [Date]
**Last Updated**: [Date]
---
## 📋 Document Properties
| Property | Value |
|----------|-------|
| **Core Team** | @PM, @TechLead, @Designer, @Engineer |
| **Stakeholders** | [List key stakeholders] |
| **Target Release** | v[X.Y] - [Quarter Year] |
| **Priority** | P0 (Critical) \| P1 (High) \| P2 (Medium) \| P3 (Low) |
| **Status** | 🟢 Approved |
| **Jira Epic** | [PROJ-XXX](link) |
---
## 🎯 1. Objective
### Problem Statement
[In 2-3 sentences, describe the problem this solves. Be specific about who has the problem and why it matters.]
**Current Pain Points:**
- [Pain point 1: e.g., Users currently spend 10 minutes per task manually...]
- [Pain point 2: e.g., 30% of users abandon the process due to...]
- [Pain point 3: e.g., Support receives 50 tickets per week about...]
### Proposed Solution
[In 2-3 sentences, describe the proposed solution at a high level.]
### Why Now?
[Why is this the right time to build this? Market opportunity? Customer demand? Technical enabler?]
---
## 📊 2. Success Metrics
### Primary Metrics (Must Achieve)
| Metric | Current State | Target | Measurement Method | Timeline |
|--------|---------------|--------|-------------------|----------|
| [e.g., User activation rate] | 10% | 25% | Analytics: users who complete onboarding | Launch + 30 days |
| [e.g., Task completion time] | 10 min | 3 min | User analytics | Launch + 60 days |
| [e.g., Support tickets] | 50/week | <10/week | Support system | Launch + 90 days |
### Secondary Metrics (Nice to Have)
- [Metric 1: e.g., User satisfaction score improves from 6.5 to 8.0]
- [Metric 2: e.g., Feature adoption reaches 50% of active users]
### Counter-Metrics (Watch for Negative Impact)
- [Metric 1: e.g., Page load time does not increase by more than 200ms]
- [Metric 2: e.g., Error rate remains below 1%]
---
## 🎭 3. User Personas & Use Cases
### Primary Persona: [Persona Name]
**Who they are**: [Description: e.g., Mid-level project manager at a 50-person company]
**Goals**:
- [Goal 1: e.g., Manage team tasks efficiently]
- [Goal 2: e.g., Track project progress in real-time]
**Pain Points**:
- [Pain 1: e.g., Current tools are too complex]
- [Pain 2: e.g., No visibility into team capacity]
**How this feature helps**: [Specific benefit for this persona]
### Secondary Persona: [Persona Name]
[Similar structure]
### Key Use Cases
**Use Case 1: [Name]**
- **Actor**: [e.g., Project Manager]
- **Goal**: [e.g., Quickly assign tasks to team members]
- **Scenario**:
1. User opens project dashboard
2. User creates new task with title and description
3. User assigns task to team member
4. Team member receives notification
5. Task appears in team member's queue
**Use Case 2: [Name]**
[Similar structure]
---
## 📝 4. User Stories & Acceptance Criteria
### Epic: [Epic Name]
#### Story 1: [User Story Title]
**As a** [user type],
**I want to** [goal/action],
**so that** [benefit/value].
**Priority**: Must Have | Should Have | Could Have | Won't Have (MoSCoW)
**Acceptance Criteria**:
- **Given** [context/precondition]
- **When** [action/event]
- **Then** [expected outcome]
- **And** [additional outcome]
**Example**:
- **Given** I am logged in as a project manager
- **When** I click the "New Task" button
- **Then** a task creation form should appear
- **And** the form should have fields for title, description, assignee, and due date
**Design Mocks**: [Link to Figma/design tool]
**Technical Notes**: [Any implementation notes from engineering]
#### Story 2: [User Story Title]
[Similar structure]
#### Story 3: [User Story Title]
[Similar structure]
---
## 🚫 5. Out of Scope (For This Release)
To maintain focus and hit our timeline, the following are explicitly **out of scope** for v[X.Y]:
- [Feature/capability 1: e.g., Mobile app support (planned for v2.0)]
- [Feature/capability 2: e.g., Integration with third-party tools]
- [Feature/capability 3: e.g., Advanced reporting and analytics]
**Future Considerations**: [Brief note about what might come next]
---
## 🔧 6. Technical Considerations
### Architecture Impact
[Brief description of how this fits into existing architecture]
**New Components:**
- [Component 1: e.g., Task assignment service]
- [Component 2: e.g., Notification queue]
**Modified Components:**
- [Component 1: e.g., User service needs to track task assignments]
### API Changes
- **New Endpoints**:
- `POST /api/v1/tasks` - Create task
- `PUT /api/v1/tasks/{id}/assign` - Assign task
- **Modified Endpoints**:
- `GET /api/v1/users/{id}` - Now includes assigned tasks count
### Database Changes
- **New Tables**: `tasks`, `task_assignments`
- **Modified Tables**: `users` (add `task_quota` field)
### Third-Party Integrations
- [Integration 1: e.g., Email service for notifications]
- [Integration 2: e.g., Calendar API for due date reminders]
### Performance Considerations
- [Consideration 1: e.g., Task list queries should use pagination (limit 50 per page)]
- [Consideration 2: e.g., Caching strategy for frequently accessed tasks]
### Security & Privacy
- [Consideration 1: e.g., Task visibility respects project-level permissions]
- [Consideration 2: e.g., Audit log for all task assignments and changes]
---
## 🎨 7. User Experience & Design
### User Flows
[Insert or link to user flow diagrams]
**Flow 1: Create and Assign Task**
```
User → Dashboard → "New Task" Button → Task Form → Fill Details → Select Assignee → Save → Notification Sent
```
### Wireframes/Mockups
[Embed screenshots or link to design files]
- [Screen 1: Task list view]
- [Screen 2: Task creation form]
- [Screen 3: Task detail view]
### Interaction Design
- **Primary Actions**: [e.g., Create Task, Assign Task]
- **Secondary Actions**: [e.g., Edit Task, Delete Task]
- **Navigation**: [e.g., Tasks accessible from main nav and project dashboards]
### Accessibility
- [e.g., All interactive elements keyboard-navigable]
- [e.g., WCAG 2.1 AA compliance for color contrast]
- [e.g., Screen reader support with proper ARIA labels]
---
## 🗓️ 8. Timeline & Milestones
| Milestone | Description | Target Date | Owner | Status |
|-----------|-------------|-------------|-------|--------|
| **Kickoff** | Design review and tech planning | [Date] | @PM | ✅ Done |
| **Design Complete** | Final mocks approved | [Date] | @Designer | ✅ Done |
| **Alpha** | Internal testing | [Date] | @Engineer | 🔵 In Progress |
| **Beta** | Limited rollout (10% users) | [Date] | @PM | ⏳ Pending |
| **GA** | General availability | [Date] | @PM | ⏳ Pending |
**Estimated Effort**: [e.g., 3 sprints, 6 weeks]
---
## 🔐 9. Go-to-Market & Launch Plan
### Rollout Strategy
- **Phase 1**: Internal beta (company employees) - Week 1-2
- **Phase 2**: Limited beta (10% of users, selected customers) - Week 3-4
- **Phase 3**: General availability (100% rollout) - Week 5
### Launch Checklist
- [ ] Product documentation updated
- [ ] API documentation published
- [ ] User guide and help articles created
- [ ] Support team trained
- [ ] Marketing materials prepared
- [ ] In-app announcements configured
- [ ] Email campaign scheduled
- [ ] Analytics dashboards set up
- [ ] Rollback plan documented
### Communication Plan
- **Internal**: Slack announcement, all-hands demo
- **External**: Blog post, email to active users, in-app notification
- **Support**: KB articles, training session, FAQ document
### Success Criteria for Launch
- Zero P0 bugs in first week
- < 5% increase in support tickets
- [Primary metric] shows improvement within 30 days
---
## ⚠️ 10. Risks & Mitigations
| Risk | Impact | Likelihood | Mitigation Strategy | Owner |
|------|--------|------------|---------------------|-------|
| [Risk 1: e.g., API performance degrades under load] | High | Medium | Load testing before launch, auto-scaling configured | @TechLead |
| [Risk 2: e.g., Users don't understand new workflow] | Medium | High | In-app onboarding tutorial, contextual help tooltips | @Designer |
| [Risk 3: e.g., Integration with email service fails] | High | Low | Fallback to alternative email provider, monitoring alerts | @Engineer |
---
## 🤔 11. Open Questions & Decisions
### Open Questions
- [ ] **Q1**: Should tasks be private or visible to all project members?
- **Status**: ⏳ Pending decision
- **Owner**: @PM
- **Due Date**: [Date]
- [ ] **Q2**: What is the maximum number of tasks a user can be assigned at once?
- **Status**: ⏳ Pending decision
- **Owner**: @TechLead
- **Due Date**: [Date]
### Key Decisions Made
- ✅ **D1**: Tasks will support single assignee only (no co-assignees in v1.0)
- **Decision Date**: [Date]
- **Rationale**: Simplifies initial implementation; can add in v2.0 based on user feedback
- ✅ **D2**: Task due dates are optional
- **Decision Date**: [Date]
- **Rationale**: Not all tasks have deadlines; forcing a date creates bad data
---
## 📚 12. References & Related Documents
- [Design Mocks](link)
- [Technical Design Doc](link)
- [API Specification](link)
- [User Research Findings](link)
- [Competitor Analysis](link)
- [Original Feature Request / Ticket](link)
---
## 💬 13. Feedback & Discussion
### Stakeholder Feedback
**[Stakeholder Name] - [Date]**
> [Quote or summary of feedback]
**Response**: [How feedback was addressed or why not incorporated]
---
**[Stakeholder Name] - [Date]**
> [Quote or summary of feedback]
**Response**: [How feedback was addressed]
### Change Log
| Date | Author | Change Description |
|------|--------|-------------------|
| [Date] | [Name] | Initial draft |
| [Date] | [Name] | Added success metrics based on analytics review |
| [Date] | [Name] | Updated timeline after tech planning meeting |
| [Date] | [Name] | Approved by stakeholders |
---
## ✅ Approval
**Approved By:**
- [ ] Product Manager: _____________________________ Date: _______
- [ ] Engineering Lead: _____________________________ Date: _______
- [ ] Design Lead: _____________________________ Date: _______
- [ ] Stakeholder(s): _____________________________ Date: _______
**Approval Date**: [Date]
---
*This PRD is a living document. Updates should be tracked in the Change Log and communicated to the core team via Slack #product-updates channel.*
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 |