doc-writing

Files (4)

• SKILL.md
• doccheck.config.json
• doccheck.py · scripts/
• test_doccheck.py · scripts/

SKILL.md (first lines)

# doc-writing

> How to write a document this user accepts, organized by document type, with a linter for the rules a machine can check.

## Master TOC

- [How to use this](#how-to-use-this)
- [The two rules that caused the most friction](#the-two-rules-that-caused-the-most-friction)
- [Universal core](#universal-core)
- [Per document type](#per-document-type)
- [When the requirement depends on context](#when-the-requirement-depends-on-context)
- [Lint before you ship](#lint-before-you-ship)
- [Keeping this skill true](#keeping-this-skill-true)

## How to use this

Read the universal core once. Then read the one section for the type you are writing, and use its skeleton as the outline. Write the document. Run `scripts/doccheck.py` on it before you call it done.

**Marker legend.** Two markers appear throughout, and both mean something specific.

1. `B12` points at consolidated rule 12 in the mined preference set. The linter quotes these ids back in its findings so a rule can be traced to its evidence.
2. `#3` is the position in the frequency ranking, meaning how many separate turns the user spent repeating the point. A high rank is not a matter of taste, it is a record of repeated correction.

The source is two real project sessions from July 2026, 262 prompts total, mined into 102 verbatim preferences and 48 consolidated rules.

## The two rules that caused the most friction

### 1. Define every term you introduce, in place (`B6`, rank `#1`)

Across roughly eight separate turns the user had to stop the work and ask what a word meant. Every one of those words was the agent's own wording, so this friction was self inflicted. The questions looked like this.

> 特别解释一下langchain 4-tool sql是什么东西 · 请解释一下es是什么 · 项目级联是啥？什么入口合并？ · 报告状态静默不达，这个是啥意思？

The rule covers acronyms, product names, internal jargon, and any phrase you coined while writing. Gloss it at first use, inside the sentence, in one of these forms.

| Form | Example |
|---|---|
| Parenthetical | `the ETL (extract, transform, load) job` |
| Dash gloss | `ETL — extract, transform, load — runs nightly` |
| Glossary row | `- **ETL**: the nightly extract, transform, load pass` |

A glossary section at the top does not excuse an unglossed term further down. If you invented the phrase while writing the sentence, that is exactly the case that needs the gloss.

### 2. A manual (手册) AND an in-app guide (引导) per feature, and a guide is a use case flow (`B13`, `B14`, rank `#2`)

Roughly ten turns, including an outright rejection the user asked be recorded permanently.

> Agent的那个引导有点儿奇怪，他就是简单的罗列了一下几个按钮，根本没有整个的流程，所有的引导它是按照功能流程来的，也就是user case来的，即使是同一大模块儿的功能，如果它有好几种使用方式/cases，那实际上应该有好几种，好几个引导才对，而不能单纯的就是把功能罗列一下，请对这个进行一个整体的优化，并且记下这个要求。

What this settles.

1. Every shipped feature gets both artifacts. A written manual, and an interactive guide inside the product. Either may be standalone or folded into the feature surface.
2. A guide is an end to end flow through a real task, never an enumeration of the buttons on screen. Listing controls was rejected by name.
3. One module with N distinct ways of being used gets N guides, one per use case.
4. Manuals and guides land feature by feature as each feature finishes, not batched at the end of the project.
5. Coverage is recursive. The manual and guide system itself, and the bug report module, each need their own manual and guide. There is no meta exemption.

The interactive guide has a fixed navigation contract, listed in [manual](#manual--手册-and-引导).

## Universal core

These apply to every document. The first ten are ranked by how often the user had to repeat them, and the last column names the `doccheck.py` check that enforces the rule mechanically.

| Rank | Rule | What it means when you are writing | Check |
|---|---|---|---|
| `#1` | Define every term in place (`B6`) | Gloss acronyms, product names, and phrases you coined, at first use | `undefined-jargon` |
| `#2` | Manual plus in-app guide per feature (`B13`, `B14`) | Both artifacts, per feature, guides as use case flows | — |
| `#3` | Prove it, say how you proved it, say how I re-prove it (`B2`) | Every claim comes from a real run, and the document states the procedure and how a tester repeats it | `missing-section` |
| `#4` | Full clickable link for every reference (`B4`) | Docs, files, code, commits, PRs, exposure points. Never a bare name or half a URL | `bare-ref` |
| `#5` | Nothing stale (`B9`, `B11`) | Audit the whole document when one wrong statement turns up, and refresh every diagram against the current design | `staleness` |
| `#6` | Diagram anywhere a diagram is possible, in mermaid (`B5`) | Architecture, data flow, storage and cache, plus one for the main logic and one per feature | `missing-diagram` |
| `#7` | Enumerate the inventory first (`B26`, `B27`) | Write the full list of items before changing any of them, then work through it, then review item by item |  — |
| `#8` | Batch what needs the user to the end (`B25`) | One block at the end for every question, authorization, and manual step, after checking whether it could be automated | — |
| `#9` | Deferred work becomes a future task with its risk (`B17`, `B18`) | Named, highlighted, each entry stating the risk and how to avoid it | `missing-section` |
| `#10` | No secret ever reaches a document (`B1`) | Reference where a credential lives, never its value. One leak had to be purged from git history | `secrets` |

Also always true, grouped by what they govern.

**Honesty of content.**

1. Nothing is guessed (`B2`). When something cannot be verified, the document says so instead of asserting it.
2. Cite the source of every fact, and for any number, precise value, or list, include the code and the generation procedure that produced it (`B3`).
3. Label every mock or demo item visibly so nobody reads it as real (`B37`).
4. Say when a behaviour is deliberate rather than an oversight, and record the reasoning (`B19`). The reader has to be able to tell an omission from a decision.
5. Being a prototype never licenses narrowing the analysis (`B29`).

**Writing.**

1. Natural human prose with the AI flavour removed (`B7`). Chinese reads as Chinese, never as a term by term translation of English jargon.
2. One document serves two audiences (`B7`). Deep enough technically for an engineer, while the top level narrative and the diagrams stay legible to a data analyst.
3. Structured, repetitive, or multi field information goes in a table (`B8`). Per entity outcomes get a classification table plus statistics.
4. Schemas, attributes, and storage formats always carry a worked example (`B20`).
5. Names state plainly what the thing is for (`B47`), documents included.

**Placement and delivery.**

1. Survey and cite every existing document on the topic before writing, and fix what you find stale on the way (`B10`, `B43`).
2. One topic, one main document (`B9`). New work merges into it. Scattered related documents get consolidated in, not left as parallel copies.
3. Documentation centralizes in the dedicated docs repo, laid out as one subdirectory for platform wide material plus one per code repo (`B30`).
4. Migrating a document means adding a link in the source repo and keeping the original, with one exception covered in [the decision rules](#when-the-requirement-depends-on-context) (`B31`).
5. A document counts as delivered once it is pushed and findable (`B39`). Verify it renders where it will be read, since a section that fails to render is a defect the user reports (`B12`).
6. Write every newly discovered requirement and every working configuration straight into the relevant document, making the working configuration its default example (`B35`).

## Per document type

### spec — design and architecture

The section skeleton, derived from the document the user promoted to the house template.

1. Purpose and scope
2. Terminology, glossing every term the document uses
3. Problem history — what went wrong before, what the old design was, why it failed
4. Architecture — mermaid architecture diagram, data flow diagram, storage and cache diagram
5. Code and data map — every module, table, and attribute with a full link, each placed at its correct position in the diagrams
6. Storage format, with a worked example
7. Operating it — what CI/CD automates, what a human does, and whether the whole flow runs without an AI agent
8. Per entity outcomes — classification table, statistics, accuracy per method, what needs human checking
9. Special cases and deliberate decisions, each flagged rather than folded silently into the general case
10. How comparable tools solve the same problem

From jajupmochi/agent-harness, MIT.

More from jajupmochi/agent-harness