Document Writing

Document Writing

Create documents that help a specific reader understand, act, decide, comply, recover, or reconstruct what happened. The skill routes first and writes second: a polished document built from the wrong document contract is still wrong.

Scope

This skill supports ten target document types:

1. Explanatory overview
2. Action guide
3. Reference or specification
4. Proposal
5. Analysis report
6. Policy or rules
7. Troubleshooting runbook
8. Record or meeting notes
9. Feature Design Doc (FDD)
10. Design System Document

The document type describes the artifact being created or assessed. Words appearing only as the subject do not select a type. For example, "write a guide to authoring FDDs" targets a guide, while "write an FDD for saved filters" targets an FDD.

Workflow

1. Identify the requested operation

Identify each separately requested document deliverable and determine whether the user wants to create, update, rewrite, review, fact-check, or normalize it. When an existing document is involved, inspect it before deciding how to proceed. Apply the workflow independently to each deliverable, preserving dependencies and shared source facts; a report and a proposal requested together keep separate document contracts. Do not split one document merely because it contains supporting explanation, recommendations, or steps.

Review is an operation, not a proposal type. A request such as "review this policy" routes to the policy type with the review operation.

Review and fact-check are non-mutating unless the user separately requests an update. They may inspect and research, but must not create, rename, or edit document files. Create, update, rewrite, and normalize are mutating operations within the requested document scope.

2. Identify the target artifact

Use evidence in this order:

1. The artifact the user explicitly asks to create or change
2. Existing document metadata, path, title, and headings
3. The reader's primary outcome
4. The content shape implied by the request

If an explicit label conflicts with the requested outcome and the choice materially changes the structure, ask one concise clarification question. Put that question directly in the user-facing response and phrase it so the user can answer the single unresolved choice; a decision note inside an artifact is not a substitute for the question.

3. Select exactly one document type per deliverable

4. Apply the Design System Document gate and select prebuilts per output set

Select Design System Document only when a requested artifact governs reusable visual or interaction decisions across product UI or any digital storefront's listing assets. A request whose only deliverable is UI, a mockup, images, video, or other produced assets is a production task, not this document type.

For each output set, choose exactly one prebuilt from semantic intent:

The requested output path never changes a prebuilt. Resolve each root in this order: a user-specified directory for that set, the location of the existing document set being changed or reviewed, then the selected prebuilt's default output root. A user-specified directory replaces only the prebuilt root; it does not collapse a multi-file set into README.md or another single file. Read only the prebuilt reference for that output set.

Read the selected type's overview and follow its operation-specific references. The ordered decision table in design-direction-workflow.md owns when to ask, write, stop, or report a partial result. Apply it independently to each set; it distinguishes new or direction-changing work, focused revisions, read-only review, and unresolved conditional branches.

Inspect available evidence before asking. For an existing set, inventory the entire tree—not only writable files—and follow its index and approval/change/decision owners before saying that an approved value is unavailable.

If the user explicitly requests both product UI and storefront visual asset systems, split the request into two coordinated Design System Document output sets and apply default and app-store-page independently. Use their separate default roots unless the user supplies one directory for each; ask once before writing if one custom root does not establish the two destinations.

Two sets for the same product and brand may share an approved upper-level direction when authoritative evidence supports it, but validate and document each set's contextual adaptations independently.

For app-store-page, follow storefront-research.md for each actually included target. It owns inclusion and identity resolution, official research, operation-specific writes, and capability-limited fallback, including the whole-set stop when neither online research nor sufficient identity evidence is available.

When a request combines a document with actual UI, image, or video production, keep the document portion under this skill and route the production portion to the appropriate capability as a separate deliverable. Do not let either portion suppress or silently replace the other. In the completion report, label document outputs and production outputs separately and attribute each to its owning workflow; do not imply that document authoring itself produced a binary asset.

Before reporting a new saved set as complete, follow the structural verification instructions in design-system-authoring.md. A structural pass does not establish direction approval or semantic quality.

5. Apply the FDD gate

Select FDD only when all of these are true:

• The subject is one product feature.
• The artifact defines what the feature is and why, including material behavior, flow, policy, scope, or alternative decisions.
• Implementers or code agents should treat the artifact as the current design decision source.

The word "feature" or "FDD" appearing as background is not enough. If the artifact teaches how to write an FDD, route to a guide. If it lists an API contract for a feature, route to reference or specification.

6. Resolve generic boundary cases

When no explicit target type settles the choice, use the reader's final action:

• Learn or understand: explanatory overview
• Complete a normal task: action guide
• Retrieve an exact fact or contract: reference or specification
• Approve or choose: proposal
• Interpret evidence: analysis report
• Comply with durable rules: policy or rules
• Recover from failure: troubleshooting runbook
• Reconstruct the past: record or meeting notes
• Govern reusable product UI or digital storefront visual asset decisions: Design System Document

Recommendations do not automatically make a report a proposal. Steps do not automatically make a policy a guide. Choose the type that controls why the document exists.

7. Load references progressively

After routing:

1. Read only the selected type's overview reference.
2. Follow that overview's operation-specific links.
3. Do not load the whole type directory.
4. Load another type's references only for a separately requested deliverable or a justified reroute, not merely for inspiration.
5. If clear evidence shows the route is wrong, discard the previous type contract, return here, and route again.

For all substantial creation, rewrite, or review work, read human-readable-writing.md. Read source-grounding.md only when factual claims require sources or verification. Read existing-document-edits.md only when modifying or reviewing an existing document.

For substantial authoring or review, read drafting-and-revision.md to connect preparation, content review, prose editing, and completion. For focused updates, normalization, or fact-checking, apply only its relevant steps to the requested scope; a mechanical correction does not require the full workflow. Read the selected type's review or validation reference for its applicable quality and completion criteria, without loading unrelated references. Type-specific structures, operation boundaries, and validation sequences take precedence over this shared method.

8. Gather context before drafting

Establish the audience, intended outcome, authoritative inputs, constraints, and output destination. Infer what is safely recoverable from supplied material or the repository. Ask only when an unresolved choice would materially change the document's scope, behavior, or tradeoffs.

Before drafting, identify the requested coverage, applicable type-specific completion conditions, and how material unknowns must be handled. Accept notes, fragments, questions, and supplied conversation records as starting material. When a new draft or substantial rewrite needs an outline, optionally organize reader questions and existing evidence using the shared drafting reference; reuse an established outline or decision note when it already serves that purpose.

Do not invent missing decisions or facts. Mark unresolved content explicitly when no live user can answer.

9. Draft and verify

Follow the selected references. Use their structure as a reader-centered default, not as filler. Generic document types may omit sections that do not help the reader. FDD follows its stricter profile and validator contract.

Review content before polishing prose: check both whether readers can find the answers they need and whether material requirements and source facts survived accurately. Resolve content issues within the operation's scope, then edit wording. If editing changes meaning, certainty, conditions, or obligations, recheck the affected passages and their dependencies. Review and fact-check report findings rather than applying corrections. Keep any type-specific structural and semantic checks in their required order.

Before delivery, confirm:

• The opening states the purpose, conclusion, outcome, or request appropriate to the type.
• Headings expose the document's logic when scanned.
• Each paragraph has one main idea.
• Facts, interpretation, decisions, and recommendations are distinguishable.
• Examples and expected results are concrete where useful.
• No empty, duplicated, or ceremonial sections remain.
• The result still matches the selected document type.
• For a multi-file Design System Document, every substantive supplied decision is in the owning prebuilt file, every required owner is linked from index.md, and the actual changed paths match the files the completion will claim.
• For a Design System Document, the operation-specific decision table was followed, the approved direction and decision classes are clear, and representative verification covers the scope required by that operation.
• No Design System Document file was created or modified in a branch where the decision table requires a stop; partial work is reported as partial.
• No supplied or verified value has been replaced by convention, and no unsupported value, policy, platform behavior, or storefront requirement has been added.
• Any unresolved choice that requires the user is asked once as a direct question in the user-facing response, not left only as an internal decision note.

File output and collision rules

• Resolve a type-specific output destination in this order: a user-specified path, the existing target's location, then the selected type or prebuilt's default location.
• A Design System Document prebuilt writes a multi-file set, so its root must be a directory. For a new set, ask once if the user provides a .md path instead of a directory. For an existing file inside a set, resolve and preserve its established set root.
• Inspect an existing target before writing.
• Update the established artifact only when the request is an update or the selected reference defines in-place lifecycle behavior.
• Do not silently overwrite a different document.
• Do not invent -v2, -final, or date-suffixed duplicates to avoid deciding what the canonical file is.
• Preserve existing platform, storefront, and custom files outside the requested change scope; "not requested" does not mean "delete" or "invalidate".
• If the user asks only for a draft in conversation, return complete Markdown without creating an unsolicited file.
• Follow type-specific location rules when the selected reference defines them; FDD is one such type.

Preservation and safety

When editing, preserve fenced code blocks, paths, identifiers, exact logs, quotations, and user-owned custom sections unless the user explicitly asks to change them. Preserve caller options and established document contracts. Warn before any instruction that can destroy data or materially disrupt a system.

Completion

Use the completion conditions established before drafting. Necessary uncertainty handled under the selected type's rules is not automatically unfinished authoring: a record can faithfully preserve an open decision, and a report can conclude that evidence is insufficient. Conversely, marking a gap does not satisfy a type's blocking requirement. Once the requested scope and required checks are satisfied, stop when only optional embellishment remains; do not narrow requested coverage or omit necessary evidence to finish sooner.

Before reporting completion, compare the resolved output contract and promised paths with the actual final artifact tree. Fix missing owners, links, or files first; if they cannot be produced, report the work as incomplete instead of claiming completion. Report the selected document type, the artifact produced or reviewed, validation performed, and any limitation that remains unverified. Never claim an unrun check passed.

For a Design System Document, also report the maturity state, the authority for the approved direction, the representative situations actually checked, and any unresolved decision. Distinguish completion of a focused revision from whole-set validation; apply the decision table's completion limits to new, direction-changing, and partial work.