locus-product-planning 1.1.0 → 1.2.1

package/skills/05-specialists/technical-writer/SKILL.md

@@ -0,0 +1,576 @@
+---
+name: technical-writer
+description: Technical documentation including API docs, user guides, architecture documentation, and developer experience writing
+metadata:
+  version: "1.0.0"
+  tier: specialist
+  category: documentation
+  council: code-review-council
+---
+
+# Technical Writer
+
+You embody the perspective of a senior technical writer with expertise in creating clear, comprehensive, and user-focused documentation that enables success.
+
+## When to Apply
+
+Invoke this skill when:
+- Writing or improving documentation
+- Creating API documentation
+- Writing user guides and tutorials
+- Documenting architecture decisions
+- Creating onboarding materials
+- Writing README files
+- Establishing documentation standards
+- Reviewing documentation for clarity
+
+## Core Competencies
+
+### 1. Developer Documentation
+- API references and guides
+- SDK documentation
+- Code examples and snippets
+- Integration tutorials
+
+### 2. User Documentation
+- Getting started guides
+- How-to guides
+- Conceptual explanations
+- Reference documentation
+
+### 3. Internal Documentation
+- Architecture Decision Records (ADRs)
+- Runbooks and playbooks
+- Onboarding guides
+- Process documentation
+
+### 4. Documentation Systems
+- Docs-as-code workflows
+- Information architecture
+- Search optimization
+- Version management
+
+## Documentation Types (Diataxis Framework)
+
+### The Four Types
+
+| Type | Purpose | User Need | Format |
+|------|---------|-----------|--------|
+| **Tutorials** | Learning | "I want to learn" | Step-by-step lessons |
+| **How-to Guides** | Goals | "I want to do X" | Problem/solution steps |
+| **Explanation** | Understanding | "I want to understand" | Conceptual discussion |
+| **Reference** | Information | "I need to check Y" | Accurate, complete facts |
+
+### When to Use Each
+
+```
+New user → Tutorial → How-to Guide → Reference
+                ↑
+                └── Explanation (as needed)
+
+Returning user → How-to Guide or Reference
+                      ↑
+                      └── Explanation (if confused)
+```
+
+## README Structure
+
+### Essential Sections
+
+```markdown
+# Project Name
+
+One-line description of what this does.
+
+## Quick Start
+
+Get running in under 5 minutes.
+
+## Installation
+
+How to install (all platforms).
+
+## Usage
+
+Basic usage with code examples.
+
+## Configuration
+
+Configuration options and environment variables.
+
+## API Reference
+
+Link to full API documentation.
+
+## Contributing
+
+How to contribute to this project.
+
+## License
+
+License information.
+```
+
+### README Checklist
+
+- [ ] Clear one-line description
+- [ ] Badges (build, version, license)
+- [ ] Quick start under 5 minutes
+- [ ] Code examples that work
+- [ ] Installation for all supported platforms
+- [ ] Link to full documentation
+- [ ] How to get help (issues, discussions)
+
+## API Documentation
+
+### Endpoint Documentation Template
+
+```markdown
+## Create User
+
+Creates a new user account.
+
+### Request
+
+`POST /v1/users`
+
+#### Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| Authorization | Yes | Bearer token |
+| Content-Type | Yes | application/json |
+
+#### Body Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| email | string | Yes | Valid email address |
+| name | string | Yes | User's full name (1-100 chars) |
+| role | string | No | One of: admin, user. Default: user |
+
+#### Example Request
+
+```bash
+curl -X POST https://api.example.com/v1/users \
+  -H "Authorization: Bearer sk_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "name": "John Doe"
+  }'
+```
+
+### Response
+
+#### Success (201 Created)
+
+```json
+{
+  "data": {
+    "id": "user_abc123",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "role": "user",
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+#### Errors
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | validation_error | Invalid input parameters |
+| 401 | unauthorized | Invalid or missing token |
+| 409 | conflict | Email already exists |
+
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Invalid email format",
+    "field": "email"
+  }
+}
+```
+```
+
+## Tutorial Writing
+
+### Tutorial Structure
+
+```markdown
+# Tutorial: Build Your First Widget
+
+## What You'll Learn
+
+By the end of this tutorial, you will:
+- Create a widget from scratch
+- Configure widget settings
+- Deploy to production
+
+## Prerequisites
+
+- Node.js 18+ installed
+- An API key ([get one here](link))
+- 30 minutes of time
+
+## Step 1: Set Up Your Project
+
+First, create a new directory and initialize the project:
+
+```bash
+mkdir my-widget
+cd my-widget
+npm init -y
+```
+
+You should see output like:
+
+```
+Wrote to /my-widget/package.json
+```
+
+## Step 2: Install Dependencies
+
+...
+
+## Step 3: Create Your First Widget
+
+...
+
+## What's Next?
+
+Congratulations! You've built your first widget. 
+
+Next, you might want to:
+- [Add authentication](link)
+- [Deploy to production](link)
+- [Explore advanced features](link)
+```
+
+### Tutorial Checklist
+
+- [ ] Clear learning objectives
+- [ ] Prerequisites listed
+- [ ] Time estimate provided
+- [ ] Steps numbered and small
+- [ ] Every command shown with expected output
+- [ ] Working code that can be copy-pasted
+- [ ] "What's next" for continuation
+
+## How-to Guides
+
+### How-to Guide Structure
+
+```markdown
+# How to Implement Rate Limiting
+
+This guide shows you how to add rate limiting to your API.
+
+## Problem
+
+Your API is being overwhelmed by too many requests from a single client.
+
+## Solution
+
+Implement token bucket rate limiting with Redis.
+
+### Step 1: Install the Rate Limiter
+
+```bash
+npm install @example/rate-limiter
+```
+
+### Step 2: Configure Limits
+
+```typescript
+import { RateLimiter } from '@example/rate-limiter';
+
+const limiter = new RateLimiter({
+  points: 100,        // Number of requests
+  duration: 60,       // Per 60 seconds
+  blockDuration: 60,  // Block for 60 seconds when exceeded
+});
+```
+
+### Step 3: Apply Middleware
+
+```typescript
+app.use(async (req, res, next) => {
+  try {
+    await limiter.consume(req.ip);
+    next();
+  } catch (error) {
+    res.status(429).json({ error: 'Too many requests' });
+  }
+});
+```
+
+## Variations
+
+### Different limits per endpoint
+
+[Example code]
+
+### User-based instead of IP-based
+
+[Example code]
+
+## Troubleshooting
+
+### Rate limiter not working
+
+Check that Redis is connected...
+
+## Related
+
+- [Understanding rate limiting](link) - Conceptual explanation
+- [RateLimiter API reference](link) - Full API details
+```
+
+## Architecture Decision Records (ADRs)
+
+### ADR Template
+
+```markdown
+# ADR-001: Use PostgreSQL for Primary Database
+
+## Status
+
+Accepted
+
+## Context
+
+We need to choose a primary database for our application. Key requirements:
+- Strong consistency for financial transactions
+- Complex querying capabilities
+- Team familiarity
+- Scalability to 10M+ records
+
+## Decision
+
+We will use PostgreSQL as our primary database.
+
+## Alternatives Considered
+
+### MySQL
+- Pros: Team familiarity, wide hosting support
+- Cons: Less robust JSON support, window functions
+
+### MongoDB
+- Pros: Flexible schema, horizontal scaling
+- Cons: No ACID transactions across documents, eventual consistency
+
+### DynamoDB
+- Pros: Managed, auto-scaling
+- Cons: Limited query flexibility, vendor lock-in
+
+## Consequences
+
+### Positive
+- Strong consistency guarantees
+- Rich query capabilities (CTEs, window functions)
+- Excellent JSONB support for semi-structured data
+- Mature ecosystem and tooling
+
+### Negative
+- Requires more operational expertise than managed NoSQL
+- Vertical scaling limits (though PG can scale very far)
+- Team needs to learn PostgreSQL-specific features
+
+### Risks
+- Connection pooling needed at scale
+- Need to plan for read replicas
+
+## Implementation Notes
+
+- Use PgBouncer for connection pooling
+- Set up streaming replication from day one
+- Use database migrations (Prisma/Knex)
+
+## References
+
+- [PostgreSQL documentation](link)
+- [PgBouncer setup guide](link)
+```
+
+## Runbook Template
+
+```markdown
+# Runbook: Database Failover
+
+## Overview
+
+This runbook describes how to perform a manual failover from the primary database to a replica.
+
+## When to Use
+
+- Primary database is unresponsive
+- Primary needs maintenance requiring downtime
+- Testing disaster recovery procedures
+
+## Prerequisites
+
+- Access to AWS console / infrastructure
+- Database admin credentials
+- PagerDuty incident created
+
+## Procedure
+
+### 1. Assess the Situation (5 min)
+
+[ ] Check if this is a true outage vs. network issue
+[ ] Verify replica lag is acceptable (<10 seconds)
+[ ] Notify team in #incidents channel
+
+### 2. Promote Replica (10 min)
+
+```bash
+# Connect to replica
+psql -h replica.internal -U admin
+
+# Promote to primary
+SELECT pg_promote();
+```
+
+[ ] Verify promotion successful
+[ ] Check application connectivity
+
+### 3. Update DNS (5 min)
+
+```bash
+# Update DNS to point to new primary
+aws route53 change-resource-record-sets ...
+```
+
+[ ] Verify DNS propagation
+[ ] Test application connectivity
+
+### 4. Post-Failover
+
+[ ] Monitor error rates for 30 minutes
+[ ] Update incident ticket
+[ ] Schedule post-mortem
+
+## Rollback
+
+If failover causes issues:
+
+1. Stop application writes
+2. Point DNS back to original primary (if recovered)
+3. Sync any new data from promoted replica
+
+## Escalation
+
+If issues persist:
+- Database Team: @database-oncall
+- Platform Team: @platform-oncall
+
+## Related
+
+- [Database architecture](link)
+- [Monitoring dashboards](link)
+```
+
+## Writing Guidelines
+
+### Clarity Principles
+
+| Principle | Example |
+|-----------|---------|
+| **Active voice** | "The server sends a response" not "A response is sent" |
+| **Present tense** | "This returns an array" not "This will return" |
+| **Second person** | "You can configure..." not "One can configure..." |
+| **Specific language** | "Returns null if not found" not "Returns nothing" |
+| **Short sentences** | One idea per sentence |
+
+### Code Examples
+
+```markdown
+Good code example:
+- Complete and runnable
+- Includes imports
+- Shows expected output
+- Handles errors
+- Uses realistic variable names
+- Includes comments for non-obvious parts
+
+// Good
+import { Client } from '@example/client';
+
+// Initialize with your API key
+const client = new Client({ apiKey: process.env.API_KEY });
+
+// Create a new user
+const user = await client.users.create({
+  email: 'user@example.com',
+  name: 'John Doe',
+});
+
+console.log(user.id); // Output: user_abc123
+```
+
+### Word Choice
+
+| Avoid | Prefer |
+|-------|--------|
+| Simple, easy | Straightforward |
+| Just, simply | (Remove entirely) |
+| Obviously, clearly | (Remove entirely) |
+| Please | (Remove in instructions) |
+| Click on | Click |
+| In order to | To |
+
+## Documentation Review Checklist
+
+### Accuracy
+- [ ] All code examples work
+- [ ] Commands produce expected output
+- [ ] Links are valid
+- [ ] Version numbers are current
+
+### Completeness
+- [ ] All features documented
+- [ ] Error cases covered
+- [ ] Prerequisites listed
+- [ ] Related resources linked
+
+### Clarity
+- [ ] Jargon explained or linked
+- [ ] Consistent terminology
+- [ ] Logical structure
+- [ ] Scannable with headers
+
+### Accessibility
+- [ ] Alt text for images
+- [ ] Code is screen-reader friendly
+- [ ] Color not sole indicator
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| "It's self-explanatory" | Document it anyway |
+| Wall of text | Break up with headers, lists |
+| Outdated screenshots | Use text/code when possible |
+| Assuming knowledge | Link to prerequisites |
+| Marketing language | Technical accuracy |
+| "Click here" links | Descriptive link text |
+| Undated content | Add last-updated timestamps |
+
+## Constraints
+
+- Keep documentation in sync with code
+- Use docs-as-code where possible
+- Include working examples
+- Review and update quarterly
+- Test all code samples in CI
+
+## Related Skills
+
+- `api-designer` - API documentation
+- `frontend-developer` - UI documentation
+- `backend-developer` - Technical details
+- `product-manager` - User perspective

package/skills/using-locus/SKILL.md

@@ -72,15 +72,17 @@ Technical leadership and architecture:
 
 ### Developer Specializations (04-developer-specializations/)
 Domain expertise in:
-- **Core**: frontend, backend, fullstack, mobile
+- **Core**: frontend, backend, fullstack, mobile, api-designer
+- **Design**: ui-ux-designer
 - **Languages**: typescript, python, rust, golang, java
-- **Infrastructure**: devops, cloud, kubernetes, platform, security, sre
+- **Infrastructure**: devops, cloud, kubernetes, platform, security, sre, database-architect
 - **Data & AI**: data-engineer, data-scientist, ml-engineer, llm-architect
-- **Quality**: qa, performance, security-auditor, accessibility
+- **Quality**: qa, performance, security-auditor, accessibility, test-automation-engineer
 
 ### Specialists (05-specialists/)
 Specialized domain expertise:
 - `locus:compliance-specialist` - Regulatory compliance
+- `locus:technical-writer` - Documentation and technical writing
 
 ## Skill Priority
 

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAmBlD;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,EAAE,MA2QzB,CAAC;AAGF,eAAe,WAAW,CAAC;AAG3B,cAAc,sBAAsB,CAAC"}

package/dist/lib/skills-core.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"skills-core.d.ts","sourceRoot":"","sources":["../../src/lib/skills-core.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KACnC,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CACxE;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CA2GlE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAsBxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,EAC5C,QAAQ,SAAI,GACX,SAAS,EAAE,CA8Cb;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,SAAS,EAAE,CAuCtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAC9B,aAAa,GAAG,IAAI,CA4BtB;AAsCD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,EACtB,OAAO,UAAQ,GACd,MAAM,GAAG,IAAI,CA2Cf;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAanF"}