document-factory

Original source / Raw SKILL.md

---
name: document-factory
description: |
  Meta-skill for creating structured documents using proven templates.

  [VAD] Creates PRDs, RFCs, ADRs, project briefs, proposals, specs, meeting notes.
  Template-based document generation with quality checklists.

  [NÄR] Use when: create document, new document, document template, write PRD,
  create RFC, write ADR, project brief, proposal, specification

  [EXPERTISE] Document architecture, structured formats, stakeholder communication
allowed-tools: Read, Grep, Glob, Write
---

# Document Factory

**Role:** Document Architect
**Purpose:** Create well-structured documents from proven templates

## When to Activate

- Creating PRDs (Product Requirements Documents)
- Writing RFCs (Request for Comments)
- Drafting ADRs (Architecture Decision Records)
- Project briefs and proposals
- Technical specifications
- Business cases and feasibility studies
- Meeting notes and decision logs

## Document Catalog

### Strategic Documents

| Document | Use Case | Template |
|----------|----------|----------|
| **PRD** | Define product requirements | `templates/prd.md` |
| **RFC** | Propose significant changes | `templates/rfc.md` |
| **Project Brief** | Initiate projects | `templates/project-brief.md` |
| **Business Case** | Justify investments | `templates/business-case.md` |

### Technical Documents

| Document | Use Case | Template |
|----------|----------|----------|
| **ADR** | Record architecture decisions | `templates/adr.md` |
| **Tech Spec** | Detailed technical design | `templates/tech-spec.md` |
| **API Spec** | Define API contracts | `templates/api-spec.md` |
| **Runbook** | Operational procedures | `templates/runbook.md` |

### Operational Documents

| Document | Use Case | Template |
|----------|----------|----------|
| **Meeting Notes** | Capture decisions | `templates/meeting-notes.md` |
| **Decision Log** | Track key decisions | `templates/decision-log.md` |
| **Incident Report** | Post-incident analysis | `templates/incident-report.md` |
| **Status Update** | Progress communication | `templates/status-update.md` |

## Document Creation Process

### Step 1: Identify Document Type

Ask:
- What decision or outcome does this document drive?
- Who is the primary audience?
- What level of detail is needed?

### Step 2: Select Template

Match need to template type (see catalog above)

### Step 3: Gather Inputs

Typical inputs needed:
- **Context:** What's the background?
- **Problem:** What are we solving?
- **Proposal:** What's the solution?
- **Alternatives:** What else was considered?
- **Impact:** What changes and who's affected?
- **Timeline:** When does this happen?

### Step 4: Draft Document

Follow template structure, adapt to context

### Step 5: Review Checklist

- [ ] Clear problem statement
- [ ] Audience-appropriate language
- [ ] Actionable next steps
- [ ] All sections completed
- [ ] Stakeholders identified

## Universal Document Principles

1. **Lead with the decision** - Put conclusions first
2. **Know your audience** - Adjust detail and jargon
3. **Be specific** - Avoid vague statements
4. **Include alternatives** - Show you considered options
5. **Define success** - How will we know it worked?
6. **Assign ownership** - Who does what by when?

## Quick Templates

### Minimal PRD

```markdown
# [Product Name] PRD

## Problem
[What problem does this solve? For whom?]

## Solution
[High-level description of the solution]

## Success Metrics
[How do we measure success?]

## Requirements
1. [Requirement 1]
2. [Requirement 2]

## Out of Scope
- [What we're NOT building]

## Timeline
[Key milestones]
```

### Minimal RFC

```markdown
# RFC: [Title]

## Summary
[One-paragraph summary]

## Motivation
[Why is this needed?]

## Proposal
[Detailed proposal]

## Alternatives Considered
1. [Alternative 1] - [Why not chosen]
2. [Alternative 2] - [Why not chosen]

## Risks
- [Risk 1]
- [Risk 2]

## Decision
[ ] Approved  [ ] Rejected  [ ] Needs More Discussion
```

### Minimal ADR

```markdown
# ADR-[NUMBER]: [Title]

**Status:** [Proposed | Accepted | Deprecated | Superseded]
**Date:** [YYYY-MM-DD]
**Deciders:** [Names]

## Context
[What is the issue that we're seeing that is motivating this decision?]

## Decision
[What is the change that we're proposing and/or doing?]

## Consequences
**Positive:**
- [Benefit 1]

**Negative:**
- [Tradeoff 1]
```

## Document Quality Standards

### Must Have
- Clear title and date
- Author/owner identified
- Executive summary for long docs
- Action items with owners

### Should Have
- Version history
- Stakeholder list
- Related documents linked
- Review/approval section

### Nice to Have
- Diagrams for complex concepts
- Glossary for specialized terms
- Appendices for detailed data

## Response Format

When creating a document:

```markdown
## [Document Type]: [Title]

[Document content following template]

---

🎯 COMPLETED: [SKILL:document-factory] [Created X document for Y purpose]
🗣️ CUSTOM COMPLETED: [SKILL:document-factory] [Document ready]
```


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### templates/prd.md

```markdown
# Product Requirements Document Template

---

```markdown
# [Product Name] PRD

**Version:** 1.0
**Author:** [Name]
**Date:** [YYYY-MM-DD]
**Status:** [Draft | Review | Approved]

---

## Executive Summary

[2-3 sentences summarizing the product, problem it solves, and key value proposition]

---

## Problem Statement

### Current State
[Describe the current situation and its limitations]

### Pain Points
1. [Pain point 1]
2. [Pain point 2]
3. [Pain point 3]

### Target Users
- **Primary:** [User type and description]
- **Secondary:** [User type and description]

---

## Solution Overview

### Vision
[One sentence describing the ideal end state]

### High-Level Description
[Paragraph describing the solution approach]

### Key Features
1. **[Feature 1]** - [Brief description]
2. **[Feature 2]** - [Brief description]
3. **[Feature 3]** - [Brief description]

---

## Success Metrics

| Metric | Current | Target | Timeframe |
|--------|---------|--------|-----------|
| [Metric 1] | [Value] | [Value] | [Timeline] |
| [Metric 2] | [Value] | [Value] | [Timeline] |

---

## Requirements

### Must Have (P0)
- [ ] [Requirement 1]
- [ ] [Requirement 2]

### Should Have (P1)
- [ ] [Requirement 1]
- [ ] [Requirement 2]

### Nice to Have (P2)
- [ ] [Requirement 1]
- [ ] [Requirement 2]

### Out of Scope
- [Explicitly excluded item 1]
- [Explicitly excluded item 2]

---

## User Stories

### [User Story 1]
**As a** [user type]
**I want to** [action]
**So that** [benefit]

**Acceptance Criteria:**
- [ ] Criteria 1
- [ ] Criteria 2

---

## Technical Considerations

### Dependencies
- [Dependency 1]
- [Dependency 2]

### Constraints
- [Constraint 1]
- [Constraint 2]

### Risks
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk 1] | [H/M/L] | [H/M/L] | [Strategy] |

---

## Timeline

| Milestone | Target Date | Status |
|-----------|-------------|--------|
| [Milestone 1] | [Date] | [ ] |
| [Milestone 2] | [Date] | [ ] |
| Launch | [Date] | [ ] |

---

## Stakeholders

| Name | Role | Responsibility |
|------|------|----------------|
| [Name] | [Role] | [Responsibility] |

---

## Appendix

### Related Documents
- [Document 1]
- [Document 2]

### Glossary
- **Term 1:** Definition
- **Term 2:** Definition
```

```

### templates/rfc.md

```markdown
# Request for Comments (RFC) Template

---

```markdown
# RFC: [Title]

**RFC Number:** RFC-[NUMBER]
**Author:** [Name]
**Date:** [YYYY-MM-DD]
**Status:** [Draft | Discussion | Final Comment | Accepted | Rejected]
**Reviewers:** [Names]

---

## Summary

[One paragraph summarizing the proposal. This should be understandable without reading the rest of the document.]

---

## Motivation

### Problem Statement
[What problem are we trying to solve?]

### Current State
[How does the current system work? What are its limitations?]

### Why Now?
[Why is this the right time to address this?]

---

## Proposal

### Overview
[High-level description of the proposed change]

### Detailed Design

#### [Component 1]
[Detailed description]

#### [Component 2]
[Detailed description]

### API Changes (if applicable)

```typescript
// Before
interface OldAPI {
  // ...
}

// After
interface NewAPI {
  // ...
}
```

### Data Model Changes (if applicable)

[Describe any changes to data structures or storage]

### Migration Strategy

[How do we get from current state to proposed state?]

---

## Alternatives Considered

### Alternative 1: [Name]

**Description:** [What is this alternative?]

**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]
- [Con 2]

**Why Not Chosen:** [Reason]

### Alternative 2: [Name]

[Same structure as above]

### Do Nothing

**Impact of not implementing this RFC:**
- [Impact 1]
- [Impact 2]

---

## Risks and Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk 1] | High/Medium/Low | High/Medium/Low | [Mitigation strategy] |
| [Risk 2] | High/Medium/Low | High/Medium/Low | [Mitigation strategy] |

---

## Rollout Plan

### Phase 1: [Name]
- **Scope:** [What's included]
- **Timeline:** [Duration]
- **Success Criteria:** [How we know it worked]

### Phase 2: [Name]
[Same structure]

### Rollback Plan
[How do we revert if something goes wrong?]

---

## Open Questions

1. [Question 1]
2. [Question 2]
3. [Question 3]

---

## Dependencies

- [Dependency 1]
- [Dependency 2]

---

## Security Considerations

[Any security implications of this change]

---

## Performance Considerations

[Any performance implications of this change]

---

## Testing Strategy

[How will this be tested?]

---

## Documentation

[What documentation needs to be created or updated?]

---

## Decision

**Status:** [ ] Approved  [ ] Rejected  [ ] Needs More Discussion

**Date:** [Decision date]

**Rationale:** [If rejected or modified, explain why]

---

## Changelog

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | [Date] | [Name] | Initial draft |
```

```

### templates/adr.md

```markdown
# Architecture Decision Record (ADR) Template

---

```markdown
# ADR-[NUMBER]: [Short Title]

**Status:** [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
**Date:** [YYYY-MM-DD]
**Deciders:** [List of people involved in the decision]
**Technical Story:** [Link to ticket/issue, if applicable]

---

## Context

[Describe the context and problem statement. What is the issue that we're seeing that is motivating this decision or change? This should be objective, describing the situation without judgment.]

### Technical Context
[Specific technical details relevant to the decision]

### Business Context
[Business drivers, constraints, or requirements]

---

## Decision

[State the decision that was made. Use active voice: "We will..." not "It was decided..."]

**We will [decision].**

### Implementation Details
[Specific details about how this will be implemented]

---

## Rationale

[Explain why this decision was made. Include the considerations that led to this conclusion.]

### Driving Factors
1. [Factor 1]
2. [Factor 2]
3. [Factor 3]

### Trade-offs Considered
[What trade-offs does this decision involve?]

---

## Alternatives Considered

### Option 1: [Name]
**Description:** [Brief description]
**Pros:** [Benefits]
**Cons:** [Drawbacks]
**Reason not chosen:** [Explanation]

### Option 2: [Name]
**Description:** [Brief description]
**Pros:** [Benefits]
**Cons:** [Drawbacks]
**Reason not chosen:** [Explanation]

---

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]
- [Benefit 3]

### Negative
- [Drawback 1]
- [Drawback 2]

### Neutral
- [Change that is neither positive nor negative]

---

## Risks

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk] | H/M/L | H/M/L | [Strategy] |

---

## Dependencies

- [Dependency 1]
- [Dependency 2]

---

## Related Decisions

- [ADR-XXX: Related Decision]
- [ADR-YYY: Another Related Decision]

---

## Notes

[Any additional notes, context, or references]

---

## Changelog

| Date | Author | Description |
|------|--------|-------------|
| [Date] | [Name] | Created |
```

---

## ADR Naming Convention

File naming: `ADR-NNNN-short-title.md`

Examples:
- `ADR-0001-use-postgresql-for-primary-database.md`
- `ADR-0002-adopt-kubernetes-for-orchestration.md`
- `ADR-0003-event-driven-architecture.md`

## ADR Status Flow

```
Proposed → Accepted → [Deprecated | Superseded]
    ↓
 Rejected
```

## Quick ADR Template (Lightweight)

For smaller decisions, use this minimal format:

```markdown
# ADR-[NUMBER]: [Title]

**Status:** [Status]
**Date:** [Date]

## Context
[Brief context]

## Decision
We will [decision].

## Consequences
- [Consequence 1]
- [Consequence 2]
```

```

### templates/tech-spec.md

```markdown
# Technical Specification Template

---

```markdown
# Technical Specification: [Feature/Component Name]

**Version:** 1.0
**Author:** [Name]
**Date:** [YYYY-MM-DD]
**Status:** [Draft | Review | Approved | Implemented]
**Reviewers:** [Names]

---

## Overview

### Purpose
[One paragraph describing what this spec covers and why]

### Scope
**In Scope:**
- [Item 1]
- [Item 2]

**Out of Scope:**
- [Item 1]
- [Item 2]

### Glossary
| Term | Definition |
|------|------------|
| [Term] | [Definition] |

---

## Background

### Current State
[Describe how the system currently works]

### Problem Statement
[What problem does this solve?]

### Related Documents
- [Link to PRD]
- [Link to relevant ADRs]
- [Link to existing documentation]

---

## Requirements

### Functional Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-1 | [Requirement] | P0/P1/P2 |
| FR-2 | [Requirement] | P0/P1/P2 |

### Non-Functional Requirements

| ID | Category | Requirement | Target |
|----|----------|-------------|--------|
| NFR-1 | Performance | [Requirement] | [Target] |
| NFR-2 | Security | [Requirement] | [Target] |
| NFR-3 | Scalability | [Requirement] | [Target] |

---

## System Design

### Architecture Overview

[High-level architecture diagram description]

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Client     │────▶│    API       │────▶│   Database   │
└──────────────┘     └──────────────┘     └──────────────┘
```

### Component Design

#### [Component 1]

**Purpose:** [What this component does]

**Responsibilities:**
- [Responsibility 1]
- [Responsibility 2]

**Interfaces:**
```typescript
interface Component1Interface {
  method1(param: Type): ReturnType;
  method2(param: Type): ReturnType;
}
```

#### [Component 2]
[Same structure as above]

### Data Design

#### Data Models

```typescript
interface EntityName {
  id: string;
  field1: Type;
  field2: Type;
  createdAt: Date;
  updatedAt: Date;
}
```

#### Database Schema

```sql
CREATE TABLE entity_name (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  field1 VARCHAR(255) NOT NULL,
  field2 INTEGER,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### Data Flow

[Describe how data flows through the system]

---

## API Design

### Endpoints

#### [POST] /api/v1/resource

**Description:** [What this endpoint does]

**Request:**
```json
{
  "field1": "value",
  "field2": 123
}
```

**Response:**
```json
{
  "id": "uuid",
  "field1": "value",
  "field2": 123,
  "createdAt": "2025-01-01T00:00:00Z"
}
```

**Error Codes:**
| Code | Description |
|------|-------------|
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |

---

## Security Considerations

### Authentication
[How users are authenticated]

### Authorization
[How access is controlled]

### Data Protection
[How sensitive data is protected]

### Threat Model
| Threat | Mitigation |
|--------|------------|
| [Threat 1] | [Mitigation] |

---

## Performance Considerations

### Expected Load
- [Metric 1]: [Value]
- [Metric 2]: [Value]

### Performance Targets
| Metric | Target | Measurement |
|--------|--------|-------------|
| Latency (p50) | < 100ms | [How measured] |
| Latency (p99) | < 500ms | [How measured] |
| Throughput | 1000 RPS | [How measured] |

### Optimization Strategies
- [Strategy 1]
- [Strategy 2]

---

## Reliability & Operations

### Failure Modes
| Failure | Detection | Recovery |
|---------|-----------|----------|
| [Failure mode] | [How detected] | [How recovered] |

### Monitoring
- [Metric/Alert 1]
- [Metric/Alert 2]

### Logging
[What is logged and at what level]

---

## Testing Strategy

### Unit Tests
[What will be unit tested]

### Integration Tests
[What will be integration tested]

### Performance Tests
[What will be performance tested]

### Test Data
[How test data will be managed]

---

## Deployment

### Prerequisites
- [Prerequisite 1]
- [Prerequisite 2]

### Deployment Steps
1. [Step 1]
2. [Step 2]

### Rollback Plan
[How to rollback if deployment fails]

### Feature Flags
[Any feature flags used]

---

## Migration Plan

### Dependencies
[What must be in place before migration]

### Steps
1. [Migration step 1]
2. [Migration step 2]

### Rollback
[How to rollback migration]

---

## Timeline

| Milestone | Target Date | Status |
|-----------|-------------|--------|
| Design Complete | [Date] | [ ] |
| Implementation | [Date] | [ ] |
| Testing | [Date] | [ ] |
| Deployment | [Date] | [ ] |

---

## Open Questions

1. [Question 1]
2. [Question 2]

---

## Appendix

### References
- [Reference 1]
- [Reference 2]

### Changelog
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | [Date] | [Name] | Initial draft |
```

```