Write, review, and improve technical documents (技术文档, 设计文档, 操作手册, 故障报告, API文档). Use when users ask to write/draft/review/improve a technical document, create an RFC/ADR, write a runbook or operation guide, produce API docs, or create any structured technical writing deliverable. Audience-aware, evidence-based, with quality gates and anti-staleness enforcement. Supports concept docs, task docs, reference docs, troubleshooting docs, and design docs (RFC/ADR).
Write, review, and improve technical documents (技术文档, 设计文档, 操作手册, 故障报告, API文档). Use when users ask to write/draft/review/improve a technical document, create an RFC/ADR, write a runbook or operation guide, produce API docs, or create any structured technical writing deliverable. Audience-aware, evidence-based, with quality gates and anti-staleness enforcement. Supports concept docs, task docs, reference docs, troubleshooting docs, and design docs (RFC/ADR).
Full document generated from audience analysis and type classification.
Use templates from templates.md as starting points.
Requires Phase 0–5 of the workflow.
Review (evaluate existing document)
Read the full document first.
Classify its type, then run the Quality Scorecard.
Report findings grouped by severity (Critical / Major / Minor).
Provide concrete before/after fixes, not vague suggestions.
Improve (refactor existing document)
Minimal-diff edits — change only what the scorecard flags; do not rewrite sections that already pass.
Preserve the author's voice and existing structure where they work.
Mandatory Gates
Gates are serial. Each must pass before the next. If a gate cannot be executed, apply the Degradation Strategy.
Gate 0: Execution Integrity
Never fabricate document content that claims to be from the codebase (commands, configs, API parameters) without verifying it actually exists.
Never claim you verified a command is runnable unless you actually executed it.
If you cannot verify a fact, mark it explicitly: <!-- UNVERIFIED: ... -->.
Gate 1: Repo Context Scan
Before writing, quickly scan for existing doc conventions (docs/, CONTRIBUTING.md, .markdownlint.json, .vale.ini). Adapt to what exists — consistency with the repo trumps this skill's defaults. If conflicting conventions are found → STOP and ASK which to follow.
Gate 2: Classify Type and Audience
Classify the document and its audience before writing anything:
Reader's Goal
Document Type
Core Question
Understand a concept
Concept doc
What is it? Why? When to use?
Complete an operation
Task doc (runbook)
How? How to verify? How to rollback?
Look up a parameter
Reference doc
Fields, types, defaults, constraints?
Diagnose a failure
Troubleshooting doc
What happened? Why? How to fix/prevent?
Record a decision
Design doc (RFC/ADR)
Why this approach? What was rejected?
If the user's request maps to multiple types → STOP and ASK before proceeding.
Audience — state explicitly: (1) who is the reader, (2) what must they do, (3) what do they already know. If audience is unclear and cannot be inferred → STOP and ASK. Mixed audience → use funnel structure (Executive Summary → Overview → Technical Detail → Appendix); load writing-quality-guide.md §Funnel Structure for the pattern.
Gate 3: Quality Scorecard
Run after writing/reviewing. Results must be reported in the output. Items marked with a doc type apply only to that type; unmarked items apply to all types.
Critical (any FAIL → document not deliverable)
Commands are copy-paste-runnable [task, troubleshooting] or code is marked as snippet [concept]
Every key step has expected output and verification [task, troubleshooting]
Document has metadata: owner + last_updated + status [all]
Terminology is consistent — zero synonym mixing [all]
Parameter/field tables complete — Type, Required, Default, Description columns all filled; no empty cells or TBD [reference]
Standard (≥ 4/6 pass)
Conclusion/core message appears in the first paragraph, not buried at the end [all — especially troubleshooting: root cause upfront]
Prerequisites are complete: permissions, environment, dependencies, inputs [task, troubleshooting]
Rollback/failure path documented with trigger conditions [task]
Title follows SPA principle (Simple ≤20 chars, Profit, Accurate) [all]
Code examples are self-contained with imports, not just fragments [task, troubleshooting, reference]
Error codes / status codes documented with trigger conditions and recommended actions [reference, when API doc]
Hygiene (≥ 4/6 pass)
Diagrams have title, legend, and terms consistent with prose [all, when diagrams present]
Cross-references to related docs where appropriate [all]
Short paragraphs; 80%+ structured info in lists/tables [all]
applicable_versions field present for version-sensitive content [all]
Maintenance trigger conditions noted (when must this doc be updated?) [task, troubleshooting]
Prevention section with quantifiable monitoring/alerting thresholds [troubleshooting]
Critical failures block delivery. Record scorecard results in output.
Degradation Strategy
Level
Condition
Behavior
Level 1: Full
Audience, type, and repo context all clear
Complete document + all gates pass
Level 2: Partial
Type clear but audience uncertain
Write with broadest reasonable audience; mark <!-- AUDIENCE: assumed ... --> at top; note in output
Level 2.5: Active Retrieval
Content gaps exist but codebase may contain answers
Before degrading to Level 3, attempt at least one round of targeted search (Grep for key terms, Glob for related files, Read for config/code). Fill gaps with retrieved evidence. If retrieval succeeds → proceed at Level 1 or 2. If retrieval fails → degrade to Level 3
Level 3: Scaffold
Insufficient info after active retrieval attempt
Generate skeleton with section headings + <!-- TODO: ... --> placeholders; list what was searched and not found; ask user to fill gaps
Never present Level 2/3 output as if it were Level 1. When a relevant codebase or doc corpus exists, always attempt Level 2.5 retrieval before degrading to Level 3. If no meaningful corpus is available (e.g., greenfield project, standalone document with no repo context), skip Level 2.5 retrieval and classify based on the information the user has provided — if audience, type, and scope are clear, proceed at Level 1 or 2 directly.
Workflow
Phase 0: Repo Context Scan (Gate 1)
Scan repository for existing doc conventions. Adapt or ask.
Phase 1: Classify and Analyze Audience (Gate 2)
Determine type, audience, knowledge gap. State these explicitly.
Phase 2: Structure
Conclusion first: lead with the core message. Do not bury it.
Group by category: related info under the same heading.
Logical progression: cause→effect, time-order, or importance-order.
Build the skeleton using the appropriate template from templates.md.
Phase 3: Write
Apply these rules while writing:
Minimal writing
Same concept → same term. Never alternate "集群" and "cluster" in one doc.
Delete filler: "其实", "就是说", "我们需要做的是" → cut.
Provide signposts: section summaries, TOC for docs > 3 screens, cross-references.
It deterministically checks the regex-decidable scorecard subset: metadata block (owner/status/last_updated), TBD/empty cells in tables, single H1 with SPA length, fenced code blocks carrying language tags, and Pangu spacing in CJK-Latin mixed text. Critical lint failures block delivery, same as scorecard Critical items.
Judgment layer — evaluate the remaining scorecard items (conclusion-first, terminology consistency, prerequisites completeness) by reading the document.
Fix Critical failures from either layer before delivering.
Reader-first: every decision (depth, terminology, structure) is driven by reader needs, not author convenience.
One doc, one job: a document serves one primary purpose. If mixed, split and cross-link.
Executable over descriptive: commands must be copy-pasteable; steps must have expected output; tasks must have verification.
No stale docs: every document has an owner and last-updated date. A stale doc is worse than no doc.
Evidence over opinion: claims need proof (logs, metrics, benchmarks, code). "It might be a network issue" without evidence is unacceptable.
Anti-Examples
In Review or Improve mode, load writing-quality-guide.md §Anti-Examples for the full list of 12 common documentation mistakes (conclusion buried, wall of text, vague diagnosis, synonym mixing, orphaned docs, etc.).
Document Maintenance (Anti-Staleness)
A stale doc is worse than no doc. When writing, also establish maintenance:
Mandatory update triggers — document MUST be updated when:
Commands, config items, or API parameters change.
Default behavior changes due to version upgrade.
Incident handling procedures or on-call routing changes.
A "followed the doc but it failed" case is reported.
Status lifecycle: active → needs-update → active (revised) or deprecated (with replacement link).
Periodic review cadence:
Frequency
Cycle
Example
High (release, deploy, incident)
Monthly
Release runbook
Medium (dev workflows)
Quarterly
Dev environment setup
Low (background knowledge)
Biannually
Architecture design doc
When delivering, recommend the appropriate review cadence for the document.
Load References Selectively
When classifying the document type (Phase 1) and building the initial skeleton:
→ Load references/templates.md for the document type template matching the classification (concept doc, task doc, reference doc, troubleshooting doc, RFC/ADR). Load only the section matching the classified type — do not load all templates.
When the audience is mixed (executives + engineers, or unknown):
→ Load references/writing-quality-guide.md §Funnel Structure for the four-layer structure pattern (Executive Summary → Overview → Technical Detail → Appendix) and section-length guidance.
When the document contains code blocks or CLI examples:
→ Load references/writing-quality-guide.md §Code Examples for code block formatting rules, language tag conventions, inline vs block decision criteria, and annotation patterns.
When in Review or Improve mode, assessing existing document quality:
→ Load references/writing-quality-guide.md §BAD/GOOD Examples and §Anti-Examples for the catalog of 12 common documentation mistakes (buried conclusions, walls of text, vague diagnosis, synonym mixing, orphaned docs) with corrected alternatives.
→ Load references/writing-quality-guide.md §Review Patterns for severity grouping (Critical / Major / Minor), before/after fix format, and common review pitfalls.
When the document requires diagrams, flowcharts, or visual structure:
→ Load references/writing-quality-guide.md §Visual Expression for diagram type selection (sequence, flowchart, ER, state), Mermaid syntax conventions, and diagram placement rules.
When the user explicitly asks about doc CI pipelines, PR templates, auto-generation, or doc-as-code infrastructure:
→ Load references/docs-as-code.md for CI check configurations, PR template structure, auto-generation tooling options, and doc ownership policies. Do not load for normal Write/Review/Improve tasks — adds ~780 tokens with no benefit for document creation.
Output Contract
Every invocation must end with this structured block. Use the exact field names.
