Tech Doc Writer¶

Write technical documents that pass one test: the target reader can complete the task independently without asking anyone.

Execution Modes¶

Write (new document from scratch)¶

• 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:

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]

Standard (≥ 4/5 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]

Hygiene (≥ 3/5 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¶

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.

Code examples — load writing-quality-guide.md §Code Examples for full patterns: - Task docs: commands must be copy-paste-runnable with expected output. - Concept docs: mark simplified examples explicitly. - All code: self-contained (includes imports), comments explain WHY not WHAT, show failure path.

Visual expression: - Use diagrams when: 3+ components interact, state transitions, sequential interactions. - Prefer Mermaid (GitHub/GitLab native) or ASCII art (diffable). - Mermaid complexity limit: Keep diagrams ≤ 15 nodes. If logic requires more, split into multiple sub-diagrams with cross-references. Overly complex Mermaid frequently fails to render. - Every diagram: title + legend + naming consistent with prose.

Title — SPA Principle: - Simple: ≤ 20 characters, no filler words - Profit: what does the reader gain? - Accurate: no exaggeration, no ambiguity

Phase 4: Quality Gate (Gate 3)¶

Run scorecard. Fix Critical failures before delivering.

Phase 5: Metadata¶

Add to the top of every document:

---
title: <Document Title>
owner: <responsible person>
status: draft | active | deprecated
last_updated: YYYY-MM-DD
applicable_versions: <e.g. Go 1.24+, MySQL 8.0>
---

Hard Rules¶

1. Reader-first: every decision (depth, terminology, structure) is driven by reader needs, not author convenience.
2. One doc, one job: a document serves one primary purpose. If mixed, split and cross-link.
3. Executable over descriptive: commands must be copy-pasteable; steps must have expected output; tasks must have verification.
4. No stale docs: every document has an owner and last-updated date. A stale doc is worse than no doc.
5. 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: 1. Commands, config items, or API parameters change. 2. Default behavior changes due to version upgrade. 3. Incident handling procedures or on-call routing changes. 4. 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:

When delivering, recommend the appropriate review cadence for the document.

Load References Selectively¶

• references/templates.md Load the template matching the classified document type (Phase 1). Do NOT load all templates — only the one needed.
• references/writing-quality-guide.md Load §Funnel Structure when audience is mixed (Gate 3). Load §Code Examples when document contains code blocks. Load §BAD/GOOD Examples when in Review or Improve mode. Load §Anti-Examples when in Review or Improve mode (12 common documentation mistakes). Load §Review Patterns when in Review mode (severity grouping, before/after fix patterns, common pitfalls). Load §Visual Expression when document needs diagrams.
• references/docs-as-code.md Load only when user explicitly asks about doc CI, PR templates, auto-generation, or doc infrastructure setup. Do NOT load this file for normal Write/Review/Improve tasks — it adds ~780 tokens with no benefit for document creation.

Output Contract¶

Every invocation must end with this structured block. Use the exact field names.

── tech-doc-writer output ──
mode:           Write | Review | Improve
degradation:    Level 1 (Full) | Level 2 (Partial) | Level 2.5 (Retrieval-Assisted) | Level 3 (Scaffold)
doc_type:       concept | task | reference | troubleshooting | design
audience:       <role> / <goal> / <prior knowledge>
scorecard:      Critical: <n>/<total> | Standard: <n>/<total> | Hygiene: <n>/<total>
files:          [list of created or changed file paths]
maintenance:    cadence: <monthly|quarterly|biannually>; triggers: <comma-separated>
assumptions:    [list of anything inferred rather than confirmed, or "none"]

Example:

── tech-doc-writer output ──
mode:           Write
degradation:    Level 1 (Full)
doc_type:       task
audience:       backend dev / deploy service / knows Docker basics
scorecard:      Critical: 4/4 | Standard: 5/5 | Hygiene: 4/5
files:          [docs/deploy-user-service.md]
maintenance:    cadence: monthly; triggers: deploy script change, infra version bump
assumptions:    [assumed reader has VPN access based on repo context]

Language¶

• Follow the language of the existing document or user's request.
• Chinese documents: Chinese prose, English for code/commands/technical terms.
• Pangu spacing (盘古之白): In CJK-Latin mixed text, always insert exactly one space between CJK characters and Latin letters/numbers. Examples:
• BAD: 使用Redis集群部署3个节点
• GOOD: 使用 Redis 集群部署 3 个节点
• Exception: no space needed inside inline code backticks, URLs, or file paths.
• Maintain consistent terminology within a document — add a glossary section if needed.

Self-Validation¶

Run scripts/run_regression.sh to verify skill integrity: - Contract tests: SKILL.md structure, reference files, template coverage - Coverage matrix: scripts/tests/COVERAGE.md