doc-coauthoring

# Document Co-Authoring Skill

## When This Skill Activates
- "Write a document", "draft a proposal"
- "Create a spec", "design document"
- "Help me write", "co-author"
- "RFC", "ADR", "technical spec"
- "Documentation", "user guide"

## Three-Stage Workflow

### Stage 1: Context Gathering

**Start with meta-context questions:**
1. Who is the audience?
2. What's the purpose/goal?
3. What decisions need to be made?
4. What constraints exist?
5. What's the deadline/urgency?

**Then info dump:**
- Ask user to share all relevant context
- Notes, prior docs, requirements
- Stakeholder preferences
- Examples of similar docs they like

**Clarifying questions:**
- Ask 3-5 targeted questions
- Ensure understanding before drafting
- Surface hidden assumptions

### Stage 2: Section-by-Section Drafting

For each section:

```
1. ASK clarifying questions for this section
2. BRAINSTORM 5-20 options/approaches
3. CURATE down to best options
4. DRAFT the section
5. REFINE based on feedback
```

**Feedback guidance:**
- "Specific feedback helps!" not just "looks good"
- "What's missing?" "What's confusing?"
- "What would [stakeholder] push back on?"

**Surgical edits:**
- Never reprint entire sections
- Use targeted replacements
- Preserve voice and flow

### Stage 3: Reader Testing

**Fresh perspective test:**
1. Imagine a reader with NO context
2. Can they answer key questions?
3. Are there gaps or ambiguities?
4. What questions would they ask?

**Predicted questions:**
```markdown
Q: What problem does this solve?
A: [Answer from doc - check clarity]

Q: Why this approach vs alternatives?
A: [Answer from doc - check completeness]

Q: What are the risks?
A: [Answer from doc - check thoroughness]
```

## Document Templates

### Technical Spec / RFC

```markdown
# [Feature Name] - Technical Specification

## Status
Draft | Review | Approved | Implemented

## Summary
[1-2 sentence overview]

## Background
[Context and problem statement]

## Goals
- [Goal 1]
- [Goal 2]

## Non-Goals
- [What this does NOT address]

## Proposed Solution
[Detailed description]

### Architecture
[Diagrams, components, data flow]

### API Changes
[Endpoints, schemas, breaking changes]

## Alternatives Considered
### Option A: [Name]
- Pros: [...]
- Cons: [...]

### Option B: [Name]
- Pros: [...]
- Cons: [...]

## Security Considerations
[Auth, data protection, attack vectors]

## Testing Plan
[How to verify correctness]

## Rollout Plan
[Phased rollout, feature flags, rollback]

## Open Questions
- [ ] [Question 1]
- [ ] [Question 2]
```

### Architecture Decision Record (ADR)

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

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
[What is the issue motivating this decision?]

## Decision
[What is the change being proposed?]

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

### Negative
- [Tradeoff 1]
- [Tradeoff 2]

### Neutral
- [Observation 1]

## Alternatives Considered
[Other options and why not chosen]
```

### Project Proposal

```markdown
# [Project Name] Proposal

## Executive Summary
[2-3 sentences for decision makers]

## Problem Statement
[What pain point are we addressing?]

## Proposed Solution
[High-level approach]

## Success Metrics
| Metric | Current | Target |
|--------|---------|--------|
| [Metric 1] | X | Y |

## Timeline
| Phase | Deliverable | Date |
|-------|-------------|------|
| Phase 1 | MVP | Week 2 |

## Resources Required
- Engineering: [X weeks]
- Design: [Y weeks]
- Other: [...]

## Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk 1] | High | [Plan] |

## Appendix
[Supporting details, research, data]
```

## Writing Principles

### Voice & Tone
- Match audience expectations
- Consistent throughout
- Active voice preferred
- Concise > verbose

### Structure
- Clear hierarchy (H1 → H2 → H3)
- Parallel structure in lists
- One idea per paragraph
- Transitions between sections

### Visuals
- Tables for comparisons
- Diagrams for architecture
- Flowcharts for processes
- Screenshots for UI

## Common Issues

| Issue | Solution |
|-------|----------|
| Too vague | Add concrete examples |
| Too detailed | Move to appendix |
| Missing context | Add Background section |
| No clear ask | Add explicit Proposal |
| Buried conclusion | Lead with Summary |

## Output Format

```markdown
## Document: [Title]

### Stage: [1-Context | 2-Drafting | 3-Review]

### Current Section
[Section being worked on]

### Questions for You
1. [Question 1]
2. [Question 2]

### Draft
[Current draft content]

### Feedback Requested
- Is the tone right?
- What's missing?
- Any concerns?
```