# Doc Co-Authoring

> Guide users through a structured workflow for collaboratively writing documents, proposals, specs, and decision docs. Uses a three-stage process: context gathering, iterative refinement, and reader testing.



Tags: Writing, Collaboration, Documentation


## Example Prompts

- Co-author a technical design doc with structured feedback loops
- Draft a product requirements document through guided iteration
- Write and reader-test an RFC or decision document

URL: https://rakenne.app/skills/doc-coauthoring/index.md

Try this skill: https://rakenne.app/a/?skill=doc-coauthoring



## Overview

Guide users through a structured workflow for collaboratively writing documents, proposals, specs, and decision docs. Uses a three-stage process: context gathering, iterative refinement, and reader testing.

## Getting Started

Add your source materials to the project workspace, then activate the *Doc Co-Authoring* skill. The agent will guide you through the process step by step.

## Example Conversation

> **You:** I want to write a one-pager decision doc for migrating our auth to OAuth2. Can we do the structured workflow?
>
> **Agent:** Sure. We'll do three stages: (1) Context gathering — I'll ask about audience, impact, and any template; (2) Refinement — we'll build each section with brainstorming and edits; (3) Reader testing — we'll check if a fresh reader can answer key questions from the doc. To start: Who's the primary audience? What should they do after reading it? Any existing template or format?
>
> **You:** Audience is eng leads and security. Goal: get a go/no-go. No template — just clear sections.
>
> **Agent:** I'll suggest: Context & problem, Options considered, Recommendation, Risks & mitigation, Next steps. We'll start with "Options considered" and "Recommendation" since those have the most unknowns. Dump any context you have (constraints, past discussions, why not other options); I'll ask follow-ups, then we'll brainstorm and draft section by section. Ready for your context dump.
>
> **You:** [Provides context.]
>
> **Agent:** I've created `decision-doc-auth-oauth2.md` with placeholders. Starting with the Recommendation section: here are 8 possible bullets based on what you shared. Which do you want to keep, remove, or combine? [Lists options.] Once you choose, I'll draft that section and we'll iterate.

## Sample Output Excerpt

Below is a representative excerpt from a decision document produced with the co-authoring workflow.

---

# Decision: Migrate Authentication to OAuth2

## Context and problem

Current cookie-based auth does not support mobile and third-party integrations. We need a standard, maintainable auth layer that works across web, mobile, and API clients.

## Options considered

| Option | Pros | Cons |
|--------|------|------|
| Stay on current system | No migration cost | Does not meet mobile/API requirements |
| OAuth2 + OIDC | Industry standard, library support, fits our stack | Migration and key-management effort |
| Build custom token layer | Full control | Non-standard, higher long-term cost |

## Recommendation

Adopt OAuth2 with OpenID Connect for identity. Use [Provider X] for issuance and our existing user store. Phase 1: web and API; Phase 2: mobile. Timeline: 8 weeks to pilot, 12 weeks to full rollout.

## Risks and mitigation

- **Risk:** Token revocation and session invalidation. **Mitigation:** Short-lived access tokens, refresh rotation, and revocation endpoint by Phase 2.
- **Risk:** Key rotation. **Mitigation:** Automated rotation and dual-key support during handover.

## Next steps

1. Security sign-off on provider and flow (Week 1).
2. Implement issuer and integrate with web app (Weeks 2–6).
3. Pilot with internal API consumers (Weeks 7–8).


---

Back to [Skill Library](https://rakenne.app/skills/index.md)