doc-author

name	doc-author
description	Use when documentation needs to be planned and written end-to-end — from a Jira task, feature spec, or verbal description through to a polished draft. Not for review-only or planning-only tasks.

Doc Author - Technical Writing Orchestrator

Manage the full lifecycle of a documentation task by coordinating specialized skills. Accept any input — a Jira task, feature spec, verbal description, or development task — and produce a reviewed, polished draft.

Core Principle

This skill orchestrates other skills. It does NOT duplicate their logic. Each phase invokes the appropriate skill and passes its output to the next phase. When a skill produces output, trust it and build on it — don't redo its work.

Input Acceptance

Accept any of these as a starting input:

• Jira task description (pasted or via MCP)
• Feature spec or PRD
• Verbal description ("We added X to Y")
• Development task ("We shipped PR #123 that adds...")
• Diff or PR reference
• Vague request ("Document the new onboarding feature")

If the input is too vague to determine what changed, who it affects, or where it lives in the product — ask clarifying questions before proceeding. Otherwise, move to Phase 1.

Workflow

Rule: Each phase invokes a sub-skill via the Skill tool. Never substitute your own knowledge for an invoked skill — trust the skill's output and build on it.

Phase 1: Plan — writing-planner

REQUIRED SUB-SKILL: Use the Skill tool to invoke writing-planner.

The writing-planner will:

1. Parse the input and extract what changed
2. Research affected articles and existing content — it does this zone-first through the context-mill skill, so don't pre-empt it with your own grep of the docs tree
3. Assess documentation scope (small / medium / large)
4. Interview the user for details it can't infer
5. Produce a documentation plan

Your role in this phase:

• Pass the user's input to writing-planner
• Let writing-planner drive the conversation — don't duplicate its questions
• When writing-planner produces a plan, present it to the user for approval

Do NOT proceed to Phase 2 until the user explicitly approves the plan.

After approval, ask the user: "Ready to start drafting, or do you want to adjust anything first?"

Phase 2: Draft — editor

REQUIRED SUB-SKILL: Use the Skill tool to invoke editor in write mode.

Pass the approved plan as input. The editor will:

1. Research existing patterns in neighboring articles
2. Write content following STE rules, Astro/MDX conventions, and the approved plan
3. Self-review the draft against its checklist

Your role in this phase:

• Pass the approved plan from Phase 1 to the editor
• Skip the editor's own planning phases (Phases 1-3) since the writing-planner already produced the plan — go straight to writing (Phase 4) and self-review (Phase 5)
• If the draft requires code snippets, use the Skill tool to invoke snippet-master. See "Code snippets" below.
• Present the draft to the user

Phase 3: Product Review — product-manager

REQUIRED SUB-SKILL: Use the Skill tool to invoke product-manager.

The product-manager will evaluate:

1. Value clarity and positioning
2. Persona-based usage (developer, PM, marketer)
3. Technical accuracy of Adapty concepts
4. Onboarding effectiveness and adoption barriers
5. Mobile context awareness

Your role in this phase:

• Pass the written draft to the product-manager for review
• Collect the product-manager's feedback
• Apply improvements that align with both the product-manager's feedback and the editor's style rules
• If the product-manager and editor rules conflict (e.g., product-manager wants more context but editor's STE rules say keep it concise), favor the product-manager for content decisions and the editor for style execution. In practice: include the information the product-manager recommends, but write it in STE-compliant style.
• Present the improved draft to the user

Phase 4: Feedback — Iterate with the User

Present the draft and ask for feedback. The user may:

• Approve → Done. Commit or finalize as appropriate.
• Request changes → Apply changes and re-present. If changes are substantial (new sections, restructured content), re-run the product-manager review on the changed sections.
• Disagree with a skill's recommendation → See "Skill Evolution" below.

Repeat this phase until the user approves.

Phase 4.5: Report back to the zone brief

Once the draft is approved, close the loop on the context the task started from. REQUIRED SUB-SKILL: invoke context-mill and follow Mode 4 — Autolog.

The point is not to append prose to a brief. It is that whoever wrote this article has just been in the SDK repo, the backend module or the spec, and that is the cheapest moment there will ever be to test what the brief claims. Report a diff: what the source says that the brief doesn't, what the brief says that turned out wrong — lead with that, it is the highest-value output — and what could not be verified.

Two rules the sub-skill states and that you must not soften: edit the brief only where command output settles it, dated; and never run mill:reviewed, because that is the owner saying "I read this and it is right", not a side effect of shipping an article.

Skip only if the whole task ran on the user's prose and no source was opened.

Phase 5: Skill Evolution (When Needed)

If user feedback at any phase contradicts a skill's instructions, evaluate whether the feedback represents:

A one-off preference (don't update the skill):

• "In this specific article, keep the intro shorter"
• "Skip the PM review for this small update"
• "Use a different heading style here because of [specific context]"

A reproducible pattern (update the skill):

• "Stop flagging X as an issue — it's always fine in our docs"
• "Always include Y in the intro — not just sometimes"
• "The product-manager should also check for Z"
• Style corrections that apply broadly: "We never use 'utilize' — add it to the banned words"
• Product corrections: "That's not how access levels work — update the product knowledge"

When updating a skill:

1. Tell the user what you're about to change and why
2. Read the current skill file using the Read tool (do NOT use @ syntax)
3. Make a targeted edit — don't rewrite the whole skill
4. Show the user the change
5. If the change affects a reference file (e.g., adapty-product-knowledge.md), update that file instead of the main SKILL.md
6. For non-trivial skill changes (new sections, structural changes, behavior changes), use the Skill tool to invoke superpowers:writing-skills to guide the update properly

Orchestration Rules

Don't duplicate skill work

Each skill has deep expertise. Don't second-guess the writing-planner's scope assessment, the editor's STE compliance, or the product-manager's persona analysis. Trust their output and focus on stitching phases together.

Keep the user in control

• Never auto-advance between phases. Always pause for user confirmation at phase boundaries.
• After Phase 1 (plan approved): Ask what to start with.
• After Phase 2 (draft ready): Present for review.
• After Phase 3 (PM review applied): Present the improved version.
• After Phase 4 (feedback applied): Check if the user is satisfied.

Handle scope mismatches

If the writing-planner assesses a "small update" but the user's feedback keeps expanding scope, flag it: "This has grown beyond the original small update scope. Want me to re-plan as a medium update?" Re-invoke writing-planner if needed.

Multi-article coordination

For tasks affecting multiple articles, the writing-planner will produce a multi-article plan with execution order. Follow that order. Draft each article separately through Phases 2-4, completing one before starting the next (unless the user prefers parallel drafting).

Code snippets

When the plan or draft calls for code snippets, use the Skill tool to invoke snippet-master. REQUIRED SUB-SKILL: snippet-master handles SDK code across all 7 platforms (iOS, Android, React Native, Flutter, Unity, Kotlin Multiplatform, Capacitor) — don't write snippets yourself.