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/templates/markdown/developer-tutorial.md

View on GitHub
# Tutorial: [Build/Create/Implement Specific Project]

**Learning Objective**: [Clear statement of what developers will learn - be specific!]

**Level**: [Beginner/Intermediate/Advanced]
**Time**: ~[X] minutes
**Last Updated**: [Date]

---

## What You'll Build

By the end of this tutorial, you'll have created:
- [Deliverable 1 - be concrete, e.g., "A REST API with authentication"]
- [Deliverable 2 - e.g., "User registration and login endpoints"]
- [Deliverable 3 - e.g., "Database persistence with SQLite"]

**Technologies Used**:
- [Language/Framework 1, e.g., "Node.js 18+"]
- [Language/Framework 2, e.g., "Express.js 4.x"]
- [Tool/Library 3, e.g., "JWT for authentication"]

**Complete Code**: [Link to GitHub repository]

---

## Prerequisites

### Required Knowledge
- [Skill 1, e.g., "JavaScript ES6+ syntax (arrow functions, async/await)"]
- [Skill 2, e.g., "Basic understanding of REST APIs"]
- [Skill 3, e.g., "Familiarity with command-line tools"]

### Required Tools
- [ ] [Tool 1 with version, e.g., "Node.js 18 or higher"]
- [ ] [Tool 2, e.g., "npm or yarn package manager"]
- [ ] [Tool 3, e.g., "Text editor (VS Code recommended)"]
- [ ] [Tool 4, e.g., "Git (for cloning starter code)"]

### Optional (Recommended)
- [ ] [Optional tool, e.g., "Postman or curl for API testing"]
- [ ] [Optional knowledge, e.g., "Docker (for containerization section)"]

**Verify your setup**:
```bash
node --version  # Should be v18.0.0 or higher
npm --version   # Should be 8.0.0 or higher
```

---

## Project Setup (5 Minutes)

### Option 1: Clone Starter Project
```bash
git clone https://github.com/example/tutorial-starter
cd tutorial-starter
npm install
```

### Option 2: Start from Scratch
```bash
mkdir my-project
cd my-project
npm init -y
npm install express dotenv
```

### Verify Setup
Start the development server:
```bash
npm run dev
```

Visit `http://localhost:3000` - you should see:
```
Hello World
```

āœ… **Checkpoint**: If you see "Hello World", your environment is ready!

---

## Step 1: [First Major Concept/Feature]

### What We're Building
[Brief explanation of what this step accomplishes and WHY it's important]

### The Code
Create `[filename]`:
```javascript
// [Brief description of file purpose]
const express = require('express');
const app = express();

// Middleware
app.use(express.json());

// Routes
app.get('/', (req, res) => {
  res.json({ message: 'Welcome to the API' });
});

// Start server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

module.exports = app;  // For testing
```

### Explanation
**Key Concepts**:
- **Line 1-2**: [Explain imports and why we need them]
- **Line 5**: [Explain middleware and its purpose]
- **Line 8-10**: [Explain route handler]

šŸ’” **Why This Matters**: [Explain the concept's real-world relevance]

### Test It
Run the server:
```bash
node server.js
```

Test the endpoint:
```bash
curl http://localhost:3000
```

**Expected Output**:
```json
{"message":"Welcome to the API"}
```

### Common Errors
āŒ **Error: "EADDRINUSE"**
- **Cause**: Port 3000 already in use
- **Fix**: Kill process on port 3000 or change PORT in code

---

## Step 2: [Second Major Concept/Feature]

### What We're Building
[Explanation - build on previous step]

### The Code
Update `[filename]` to add [feature]:
```javascript
// Add new imports
const bcrypt = require('bcrypt');
const jwt = require('jsonwebtoken');

// New route for user registration
app.post('/register', async (req, res) => {
  try {
    const { username, password } = req.body;

    // Validate input
    if (!username || !password) {
      return res.status(400).json({ error: 'Username and password required' });
    }

    // Hash password
    const hashedPassword = await bcrypt.hash(password, 10);

    // Save user (simplified - no database yet)
    users.push({ username, password: hashedPassword });

    res.status(201).json({ message: 'User created successfully' });
  } catch (error) {
    res.status(500).json({ error: 'Registration failed' });
  }
});
```

### Explanation
**New Concepts**:
- **bcrypt**: [Explain password hashing and security]
- **Async/Await**: [Explain asynchronous operations]
- **Error Handling**: [Explain try/catch pattern]

**Security Note**: šŸ”’ Never store plain-text passwords!

### Test It
Create a new user:
```bash
curl -X POST http://localhost:3000/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123"}'
```

**Expected Output**:
```json
{"message":"User created successfully"}
```

### Checkpoint āœ…
You should now have:
- Working Express server
- User registration endpoint
- Password hashing with bcrypt

---

## Step 3: [Third Major Concept/Feature]

[Follow same pattern: What we're building → Code → Explanation → Test → Common Errors]

---

## Step 4: [Additional Steps as Needed]

[Continue progressive learning pattern]

---

## Testing Your Application

### Unit Tests
Create `tests/api.test.js`:
```javascript
const request = require('supertest');
const app = require('../server');

describe('User Registration', () => {
  it('should create a new user', async () => {
    const res = await request(app)
      .post('/register')
      .send({ username: 'bob', password: 'test123' });

    expect(res.statusCode).toBe(201);
    expect(res.body.message).toBe('User created successfully');
  });
});
```

Run tests:
```bash
npm test
```

---

## Extensions & Next Steps

### What You've Learned
āœ… [Skill/concept 1 learned]
āœ… [Skill/concept 2 learned]
āœ… [Skill/concept 3 learned]

### Challenge Yourself
Try adding these features on your own:
1. **Easy**: [Beginner challenge, e.g., "Add email validation"]
2. **Medium**: [Intermediate challenge, e.g., "Add password reset functionality"]
3. **Hard**: [Advanced challenge, e.g., "Add OAuth2 authentication"]

### Next Tutorials
- [Related tutorial 1]
- [Related tutorial 2]
- [Advanced tutorial building on this]

### Further Reading
- [Link to deeper documentation]
- [Link to related concepts]
- [Link to production deployment guide]

---

## Complete Code

The complete working code for this tutorial is available at:
**GitHub**: [Repository URL]

**Project Structure**:
```
project/
ā”œā”€ā”€ server.js
ā”œā”€ā”€ routes/
│   ā”œā”€ā”€ auth.js
│   └── users.js
ā”œā”€ā”€ middleware/
│   └── authenticate.js
ā”œā”€ā”€ tests/
│   └── api.test.js
ā”œā”€ā”€ package.json
└── .env.example
```

---

## Troubleshooting

### Common Issues

**Module not found errors**
- Run `npm install` to install all dependencies
- Check package.json includes all required packages

**Port already in use**
- Change PORT in .env file
- Kill process: `lsof -ti:3000 | xargs kill`

**Authentication not working**
- Verify JWT_SECRET in .env
- Check token expiration time
- Ensure Authorization header format: `Bearer <token>`

---

## Additional Resources

**Documentation**:
- [Official docs link]
- [API reference link]

**Tools**:
- [Postman Collection](link)
- [Insomnia Workspace](link)

**Community**:
- [Forum/Discord link]
- [Stack Overflow tag]

---

**Tutorial Author**: [Name]
**Last Tested**: [Date] with [version info]
**Feedback**: [How to provide feedback on tutorial]
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: 471kUpdated 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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated 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