| name | doc-coauthoring |
| description | Collaborative document writing with structured workflow. Activates for "write document", "draft proposal", "create spec", "documentation", "co-author", "help me write", "RFC", "design doc". |
| allowed-tools | ["Read","Write","Edit","Task","AskUserQuestion"] |
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:
- Who is the audience?
- What's the purpose/goal?
- What decisions need to be made?
- What constraints exist?
- 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:
- Imagine a reader with NO context
- Can they answer key questions?
- Are there gaps or ambiguities?
- What questions would they ask?
Predicted questions:
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
# [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)
# 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
# [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
## 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?
