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/billing-srs.md

View on GitHub
# Software Requirements Specification: Payment Processing System

---
**Document ID**: SRS-PAYMENT-001
**Version**: 1.0.0
**Date**: 2025-01-15
**Author**: Product Team
**Status**: Approved
**Classification**: High-Risk, Compliance-Critical

TOKEN_BUDGET: 1200
TIER: 3 (Example)
LOAD_TRIGGER: Few-shot example for SRS creation
---

## 1. Introduction

### 1.1 Purpose

This Software Requirements Specification (SRS) defines the functional and non-functional requirements for the Payment Processing System, a PCI-DSS compliant payment gateway for e-commerce transactions.

**Audience**: Developers, QA engineers, project managers, compliance auditors

### 1.2 Scope

The Payment Processing System will:
- Process credit card, debit card, and digital wallet payments
- Integrate with third-party payment providers (Stripe, PayPal)
- Handle payment authorization, capture, and refunds
- Store tokenized payment information securely
- Generate transaction reports and analytics

**Out of Scope**:
- Cryptocurrency payments
- Point-of-sale (POS) terminal integration
- Buy Now Pay Later (BNPL) services

### 1.3 Definitions and Acronyms

| Term | Definition |
|------|------------|
| **PCI-DSS** | Payment Card Industry Data Security Standard |
| **Tokenization** | Replacing sensitive card data with non-sensitive tokens |
| **3DS** | 3D Secure, an authentication protocol for online payments |
| **CVV** | Card Verification Value |
| **Authorization** | Reserving funds on a customer's card |
| **Capture** | Transferring authorized funds to merchant account |

### 1.4 References

- IEEE Std 830-1998 (Software Requirements Specification)
- PCI-DSS v4.0 Requirements
- Stripe API Documentation v2023-10-16
- GDPR Article 32 (Security of Processing)

---

## 2. Overall Description

### 2.1 Product Perspective

The Payment Processing System is a backend microservice that integrates with:
- **E-commerce Platform**: Receives payment requests from checkout flow
- **Payment Providers**: Stripe (primary), PayPal (secondary)
- **Fraud Detection Service**: Kount for transaction risk scoring
- **Accounting System**: SAP for revenue recognition
- **Notification Service**: Sends payment confirmations via email/SMS

### 2.2 Product Functions

```mermaid
graph LR
    A[Customer] --> B[Checkout]
    B --> C[Payment Service]
    C --> D[Stripe]
    C --> E[PayPal]
    C --> F[Fraud Detection]
    C --> G[Database]
    C --> H[Notifications]
```

### 2.3 User Classes and Characteristics

| User Class | Characteristics | Technical Expertise |
|------------|----------------|---------------------|
| **End Customers** | Online shoppers making purchases | Low |
| **Merchants** | E-commerce store owners monitoring transactions | Medium |
| **Support Agents** | Handle payment disputes and refunds | Medium |
| **System Admins** | Configure payment providers and rules | High |
| **Auditors** | Review PCI-DSS compliance | High |

### 2.4 Operating Environment

- **Backend**: Node.js 20 LTS, Express.js
- **Database**: PostgreSQL 15 (primary), Redis 7 (caching)
- **Infrastructure**: AWS (ECS Fargate, RDS, ElastiCache)
- **Payment Providers**: Stripe API v2023-10-16, PayPal REST API v2
- **Compliance**: PCI-DSS SAQ D (Merchant Level 1)

### 2.5 Design and Implementation Constraints

- **PCI-DSS Compliance**: No storage of CVV or full card numbers
- **Regulatory**: GDPR (EU), CCPA (California), PSD2 (Strong Customer Authentication)
- **Performance**: 99.95% uptime SLA
- **Security**: TLS 1.3, encrypted data at rest (AES-256)

---

## 3. System Features

### 3.1 Payment Authorization

**Priority**: Must-Have
**Risk**: High

#### 3.1.1 Description

Authorize a payment amount on a customer's payment method without capturing funds.

#### 3.1.2 Functional Requirements

**FR-PAY-001**: The system shall accept payment authorization requests with the following parameters:
- Amount (decimal, 2 decimal places)
- Currency (ISO 4217 code)
- Payment method (card, PayPal, Apple Pay)
- Customer ID (UUID)
- Order ID (alphanumeric)

**Acceptance Criteria**:
```gherkin
Given a customer has a valid credit card
When they submit an order for $99.99 USD
Then the system shall authorize $99.99 on their card
And return an authorization ID within 3 seconds
And reserve the funds for 7 days
```

**FR-PAY-002**: The system shall validate payment methods before authorization:
- Card number checksum (Luhn algorithm)
- Expiration date (must be future date)
- CVV (3-4 digits)
- Billing ZIP code

**FR-PAY-003**: The system shall implement 3D Secure (3DS) for transactions:
- EU transactions >€30
- Flagged high-risk transactions
- Customer-requested authentication

**FR-PAY-004**: The system shall return authorization results:
- **Success**: Authorization ID, authorized amount, expiration timestamp
- **Failure**: Error code, user-friendly message, retry flag

#### 3.1.3 Test Cases

| Test ID | Scenario | Expected Result |
|---------|----------|-----------------|
| TC-PAY-001 | Valid card, sufficient funds | Authorization approved |
| TC-PAY-002 | Invalid card number (Luhn check fail) | Authorization rejected, error code INVALID_CARD |
| TC-PAY-003 | Expired card | Authorization rejected, error code EXPIRED_CARD |
| TC-PAY-004 | Insufficient funds | Authorization declined, error code INSUFFICIENT_FUNDS |
| TC-PAY-005 | 3DS required, customer completes auth | Authorization approved after 3DS |
| TC-PAY-006 | 3DS required, customer cancels | Authorization rejected, error code 3DS_FAILED |

---

### 3.2 Payment Capture

**Priority**: Must-Have
**Risk**: High

#### 3.2.1 Description

Capture previously authorized funds and transfer to merchant account.

#### 3.2.2 Functional Requirements

**FR-PAY-010**: The system shall capture authorized payments:
- Capture full amount (default)
- Capture partial amount (e.g., $50 of $100 authorization)
- Capture within authorization window (7 days)

**FR-PAY-011**: The system shall prevent double captures:
- Track capture status (pending, captured, failed)
- Idempotency keys for duplicate requests
- Maximum one capture per authorization

**FR-PAY-012**: The system shall support delayed capture:
- Orders not yet shipped (authorize now, capture on shipment)
- Manual review (fraud check before capture)
- Configurable auto-capture window (24-168 hours)

---

### 3.3 Refund Processing

**Priority**: Must-Have
**Risk**: Medium

#### 3.3.1 Functional Requirements

**FR-PAY-020**: The system shall process refunds:
- Full refunds (100% of captured amount)
- Partial refunds (e.g., $30 of $100 order)
- Multiple partial refunds (up to total captured amount)
- Refund window: 180 days from capture

**FR-PAY-021**: The system shall track refund reasons:
- Customer requested (voluntary)
- Defective product
- Order not received
- Duplicate charge
- Fraudulent transaction

**FR-PAY-022**: The system shall notify stakeholders:
- Customer: Email confirmation with refund timeline
- Merchant: Refund deducted from payout
- Accounting: Refund journal entry

---

### 3.4 Tokenization

**Priority**: Must-Have
**Risk**: Critical (PCI-DSS)

#### 3.4.1 Functional Requirements

**FR-PAY-030**: The system shall tokenize sensitive card data:
- Replace PAN (Primary Account Number) with token
- Store token in database (not card number)
- Tokens are single-use or reusable (customer preference)

**FR-PAY-031**: The system shall NOT store:
- Full card numbers (only last 4 digits)
- CVV (Card Verification Value)
- Magnetic stripe data

**FR-PAY-032**: The system shall use provider tokenization:
- Stripe: PaymentMethod tokens
- PayPal: Billing agreements
- Tokens stored with customer profile for future payments

---

## 4. External Interface Requirements

### 4.1 User Interfaces

**UI-001**: The system shall NOT provide a customer-facing UI (handled by e-commerce platform)

**UI-002**: The system shall provide an Admin Dashboard for:
- Transaction search and filtering
- Refund approval workflow
- Payment provider configuration
- Reporting and analytics

### 4.2 Hardware Interfaces

Not applicable (cloud-native, no hardware dependencies)

### 4.3 Software Interfaces

**SI-001**: Stripe API Integration
- **Interface**: REST API over HTTPS
- **Endpoint**: `https://api.stripe.com/v1/`
- **Authentication**: Bearer token (secret key)
- **Data Format**: JSON
- **Operations**: Create PaymentIntent, Confirm Payment, Create Refund

**SI-002**: PayPal REST API Integration
- **Interface**: REST API over HTTPS
- **Endpoint**: `https://api.paypal.com/v2/`
- **Authentication**: OAuth 2.0
- **Data Format**: JSON
- **Operations**: Create Order, Authorize Payment, Capture Payment

**SI-003**: Fraud Detection Service (Kount)
- **Interface**: REST API over HTTPS
- **Data Sent**: Transaction amount, customer IP, email, device fingerprint
- **Data Received**: Risk score (0-100), recommendation (approve, review, decline)

### 4.4 Communication Interfaces

**CI-001**: All external communications shall use TLS 1.3
**CI-002**: Webhook endpoints shall validate signatures (HMAC-SHA256)
**CI-003**: API rate limits: 1000 requests/minute per merchant

---

## 5. Non-Functional Requirements

### 5.1 Performance Requirements

**NFR-PERF-001**: Payment authorization shall complete within 3 seconds (p95)
**NFR-PERF-002**: System shall handle 1000 transactions per second (peak load)
**NFR-PERF-003**: Database queries shall complete within 100ms (p95)

### 5.2 Safety Requirements

**NFR-SAFE-001**: Payment data loss tolerance: Zero (mission-critical)
**NFR-SAFE-002**: Automated backups: Every 15 minutes, retained for 30 days
**NFR-SAFE-003**: Disaster recovery: RPO <15 minutes, RTO <1 hour

### 5.3 Security Requirements

**NFR-SEC-001**: Data encryption at rest: AES-256
**NFR-SEC-002**: Data encryption in transit: TLS 1.3
**NFR-SEC-003**: Password storage: bcrypt with cost factor 12
**NFR-SEC-004**: API authentication: OAuth 2.0 + API keys
**NFR-SEC-005**: PCI-DSS compliance: Annual audit (SAQ D)
**NFR-SEC-006**: Penetration testing: Quarterly by third-party

### 5.4 Software Quality Attributes

**Availability**:
- **NFR-AVAIL-001**: 99.95% uptime (4.38 hours downtime/year)
- **NFR-AVAIL-002**: Planned maintenance windows: Off-peak hours only

**Maintainability**:
- **NFR-MAINT-001**: Code coverage: >80% (unit + integration tests)
- **NFR-MAINT-002**: Deployment frequency: On-demand, zero-downtime

**Scalability**:
- **NFR-SCALE-001**: Horizontal scaling: Auto-scale based on CPU >70%
- **NFR-SCALE-002**: Database connection pooling: Max 100 connections per instance

**Reliability**:
- **NFR-REL-001**: Payment success rate: >99.5% (excluding declined cards)
- **NFR-REL-002**: Idempotency: All payment operations idempotent (24-hour window)

---

## 6. Other Requirements

### 6.1 Compliance Requirements

**COMP-001**: PCI-DSS v4.0 compliance (Merchant Level 1)
**COMP-002**: GDPR compliance (data retention, right to erasure)
**COMP-003**: PSD2 Strong Customer Authentication (EU transactions)
**COMP-004**: SOC 2 Type II certification (annual audit)

### 6.2 Logging and Monitoring

**LOG-001**: All payment events logged: Authorization, capture, refund, failure
**LOG-002**: Structured logging: JSON format with correlation IDs
**LOG-003**: Log retention: 7 years (financial regulations)
**LOG-004**: Sensitive data masking: Card numbers (last 4 digits only), CVV (never logged)

**MON-001**: Real-time monitoring: Payment success rate, latency, error rate
**MON-002**: Alerting: PagerDuty for critical failures (success rate <95%)
**MON-003**: Dashboards: Grafana for transaction volume, revenue, errors

---

## Appendix A: Glossary

| Term | Definition |
|------|------------|
| **Authorization** | Reserving funds on a customer's payment method |
| **Capture** | Transferring authorized funds to merchant account |
| **Chargeback** | Customer-initiated reversal of a payment |
| **Merchant** | Business selling goods/services online |
| **Payment Gateway** | Service that authorizes payments |
| **Tokenization** | Replacing sensitive data with non-sensitive tokens |

---

## Appendix B: Requirements Traceability Matrix

| Req ID | Description | Design Component | Test Case | Priority | Status |
|--------|-------------|------------------|-----------|----------|--------|
| FR-PAY-001 | Accept authorization requests | PaymentController | TC-PAY-001 | Must | ✅ Done |
| FR-PAY-002 | Validate payment methods | ValidationService | TC-PAY-002 | Must | ✅ Done |
| FR-PAY-003 | Implement 3D Secure | ThreeDSService | TC-PAY-005 | Must | ⏳ In Progress |
| FR-PAY-010 | Capture payments | CaptureService | TC-PAY-010 | Must | 📋 Planned |

---

**End of SRS Example - Payment Processing System**
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