doc

Files (1)

• SKILL.md

SKILL.md (first lines)

Maintain documentation under this repository's documentation policy. **The implementation is the absolute source of truth.**

# Documentation Policy

1. **Repository markdown must contain no WHAT or HOW that is derivable from code or scripts.** AI agents and contributors read code directly; restating it in markdown creates drift, not value. If a markdown section can be reconstructed by reading the code, delete it.
2. **WHY and non-derivable constraints live in JSDoc at the closest code.** Spec citations, invariants, intended contracts, and known limitations belong in JSDoc on the symbol they constrain. Architecture-level WHY goes in module-level JSDoc at the owning package's entry point (`src/index.ts`).
3. **JSDoc scope depends on visibility:**
   - **Public API symbols** (exported from a published package entry point — lands in `.d.ts` and IDE hover) MAY contain WHAT for end users.
   - **Internal code** JSDoc must not restate WHAT — only WHY, constraints, and non-obvious contracts.
4. **Do NOT create new `ARCHITECTURE.md`, `docs/*.md`, or similar explanatory markdown.** That content belongs in JSDoc (rule 2).
5. **Exempt — rule READMEs** (`packages/@markuplint/rules/src/*/README.md` + `README.ja.md`): these are website source (user-facing). Both languages must stay in sync — updating only one is a recurring mistake.
6. **Exempt — package READMEs** (`packages/**/README.md`): npm-facing user documentation, not covered by rule 1.
7. **No plan-relative concepts** in JSDoc, test names, or documentation: Phase/Step numbers, "this PR", "the old implementation", "to be introduced". Write self-contained descriptions of current behavior and intentional absences.
8. **No issue or PR numbers in code comments, JSDoc, or `describe` / `test` names.** A number means nothing without opening the tracker; write the reason instead. Existing code carries many such comments — do not imitate them. The exceptions are the rule-spec test ID convention (`[rule-name-issue-NNNN-001]`, required by `packages/@markuplint/rules/CLAUDE.md`), fixture file names that follow an existing pattern (`issue-4054.spec.ts`), and PR bodies and commit messages.

# Rules

- Use the language specified in each document
- Do not modify the implementation when updating documentation — do not change function bodies, type definitions, export statements, or even the ordering of declarations
- Do not include specific dependency version numbers (e.g., a version of a parser library) — versions change frequently and cause maintenance burden. `package.json` is the source of truth. Specification versions like ARIA 1.3 are not dependencies and may be mentioned.
- If the intent of code or documentation is unclear, ask the user rather than guessing

# JSDoc

- Every exported function and type must have a JSDoc comment
- Required tags:
  - `@param` — for each parameter; type annotation may rely on TypeScript, but a description is mandatory
  - `@returns` — description of the return value is mandatory
  - `@template` — for each type parameter; include a description
- Do not add redundant type annotations that TypeScript already provides — describe purpose, semantics, and constraints

# Final Step

After all documentation changes are complete, run `yarn lint` and fix any errors before committing.

What `yarn lint` covers differs between branches — `package.json` `scripts.lint` is the source of truth.

From markuplint/markuplint, MIT.

More from markuplint/markuplint