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/adr-microservices.md

View on GitHub
# ADR-001: Adopt Microservices Architecture over Monolith

---
**Status**: Accepted
**Date**: 2025-01-10
**Deciders**: Engineering Team, CTO, Product Lead
**Supersedes**: None
**Superseded by**: None

TOKEN_BUDGET: 400
TIER: 3 (Example)
LOAD_TRIGGER: Few-shot example for ADR creation
---

## Context

Our e-commerce platform currently runs as a single Ruby on Rails monolith deployed on Heroku. We're experiencing several challenges:

1. **Scaling limitations**: Billing service needs 10x more resources than catalog service, but we scale the entire monolith
2. **Deployment risk**: Every deployment affects all features, leading to slow release cycles (monthly deploys)
3. **Team bottlenecks**: 15 engineers working on same codebase, merge conflicts frequent
4. **Compliance isolation**: Billing (PCI-DSS) and user data (GDPR) require strict isolation, hard in a monolith
5. **Technology lock-in**: Stuck on Rails 5.2, can't experiment with new stacks (Go for performance, Node.js for real-time)

**Key Question**: Should we migrate to microservices or continue evolving the monolith?

---

## Decision

We will migrate to a microservices architecture with the following services:

| Service | Responsibility | Tech Stack | Team |
|---------|---------------|------------|------|
| **User Service** | Auth, profiles, GDPR | Node.js | Identity Team |
| **Catalog Service** | Products, inventory | Rails (existing code) | Catalog Team |
| **Cart Service** | Shopping cart, sessions | Node.js + Redis | Checkout Team |
| **Billing Service** | Payments, PCI-DSS | Go | Payment Team |
| **Notification Service** | Email, SMS, push | Python + Celery | Growth Team |
| **API Gateway** | Routing, auth, rate limiting | Kong | Platform Team |

**Migration Strategy**: Strangler Fig Pattern (gradual extraction, not big bang rewrite)

---

## Rationale

### Why Microservices?

**Independent Scaling**:
- Billing service: 5 instances during peak hours
- Catalog service: 2 instances (mostly reads, cached)
- **Cost savings**: ~40% reduction vs scaling entire monolith

**Faster Deployments**:
- Teams deploy independently (no coordination)
- Smaller services = faster CI/CD (5 mins vs 30 mins)
- Blue-green deployments per service
- **Target**: Daily deploys per team

**Compliance Isolation**:
- Billing service: Isolated network, PCI-DSS certified
- User service: GDPR-compliant data retention policies
- **Audit**: Easier to demonstrate compliance per service

**Team Autonomy**:
- Each team owns a service end-to-end
- Choose best tech stack per service
- Faster iteration (no monolith coordination)

**Failure Isolation**:
- If notification service fails, checkout still works
- Circuit breakers prevent cascading failures
- **Improved uptime**: 99.9% → 99.95% target

---

## Consequences

### Positive

✅ **Scalability**: Scale services independently based on load
✅ **Deployment velocity**: Teams ship daily instead of monthly
✅ **Technology flexibility**: Use best tool per service (Go for performance, Node for real-time)
✅ **Team ownership**: Clear boundaries reduce coordination overhead
✅ **Compliance**: Easier PCI-DSS and GDPR certification per service
✅ **Resilience**: Failures isolated to specific services

---

### Negative

❌ **Operational complexity**: More services to monitor, deploy, and maintain
- Mitigation: Invest in observability (Datadog), automation (Terraform, Helm)

❌ **Distributed system challenges**: Network latency, eventual consistency, distributed transactions
- Mitigation: Use sagas for distributed workflows, avoid distributed transactions

❌ **Data consistency**: No ACID transactions across services
- Mitigation: Event-driven architecture (Kafka) for eventual consistency

❌ **Testing complexity**: Integration tests span multiple services
- Mitigation: Contract testing (Pact), service virtualization

❌ **Initial migration cost**: 6-9 months to fully migrate
- Mitigation: Strangler Fig pattern (gradual migration, immediate value)

---

## Alternatives Considered

### Alternative 1: Modular Monolith

**Description**: Keep single codebase, organize into strict modules with clear boundaries

**Pros**:
- Simpler operations (one deployment)
- ACID transactions across modules
- Easier local development

**Cons**:
- Still requires scaling entire application
- Technology locked to Rails
- Team coordination still required
- **Rejected because**: Doesn't solve scaling or compliance isolation needs

---

### Alternative 2: Monolith + Background Workers

**Description**: Extract async jobs (email, reports) to Sidekiq workers, keep core logic in monolith

**Pros**:
- Low-hanging fruit (easy to implement)
- Isolate expensive background jobs

**Cons**:
- Doesn't solve billing isolation (PCI-DSS)
- Still monolith deployment risk
- Doesn't enable team autonomy
- **Rejected because**: Partial solution, doesn't address core problems

---

### Alternative 3: Serverless (AWS Lambda)

**Description**: Break into serverless functions (Lambda per API endpoint)

**Pros**:
- Auto-scaling built-in
- Pay-per-use pricing

**Cons**:
- Cold start latency (not acceptable for checkout)
- Vendor lock-in (AWS)
- Complex orchestration (Step Functions)
- Limited runtime (15-minute timeout)
- **Rejected because**: Too granular, operational complexity outweighs benefits

---

## Implementation Plan

### Phase 1: Extract Notification Service (Month 1-2)
- Low risk, isolated functionality
- Proof of concept for microservices

### Phase 2: Extract Billing Service (Month 3-5)
- High priority (PCI-DSS compliance)
- Use strangler pattern (dual-write during migration)

### Phase 3: Extract User Service (Month 6-7)
- GDPR compliance
- Authentication as separate service

### Phase 4: Extract Cart Service (Month 8-9)
- Real-time cart updates (WebSockets)
- Redis-backed for performance

**Validation Criteria**: Each service deployed to production, handling 10% traffic before cutover

---

## Related Decisions

- **ADR-002**: Choose Kafka for inter-service communication (linked)
- **ADR-003**: Adopt API Gateway (Kong) for routing and auth (linked)
- **ADR-005**: Use Docker + Kubernetes for deployment (linked)

---

## Notes

**Key Metrics to Track**:
- Deployment frequency (target: daily per team)
- Mean time to recovery (MTTR) (target: <30 mins)
- Service uptime (target: 99.95%)
- API latency (target: p95 <200ms)

**Review Date**: 2025-07-10 (6 months after full migration)

---

**End of ADR Example - Microservices Architecture**
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