update-docs

---
name: update-docs
description: "Update wiki markdown docs for syntax correctness, readability, link integrity, heading hierarchy normalization, and code block language tagging. Use when a user asks to clean up markdown formatting and improve clarity while preserving technical meaning."
argument-hint: "Provide one or more wiki/*.md paths and optional scope (syntax-only, readability, or full pass)"
---

# Update Wiki Docs

Read markdown files in the `wiki/` folder, fix markdown syntax issues, and improve readability without changing technical intent.

## When To Use

- The user asks to clean, polish, or normalize markdown docs in `wiki/`
- Headings/lists/code fences/tables render incorrectly
- Documentation is hard to scan due to long paragraphs or inconsistent structure
- A doc needs editorial cleanup before sharing or release

## Scope

Primary scope:

- Files under `wiki/**/*.md`, but can be used on any markdown file in the repo if specified by the user
- Skip any files starting with `_` (e.g. `_footer.md`) or non-markdown files (e.g. `LICENSE.txt`) to avoid unintended edits to non-doc files or templates.

Baseline actions:

- Correct markdown syntax
- Correct general readability issues
- Run link integrity pass for obvious broken links and anchors
- Normalize heading hierarchy and section flow
- Add or correct code block language tags when known

Expanded actions (when user allows full pass):

- Improve list/table/code-block consistency
- Standardize terminology and naming across the document
- Flag stale or unverifiable claims for follow-up

## Style Rules

- Write in concise technical style that remains approachable to non-expert users
- Prefer short to medium sentences; avoid unnecessary long sentences
- Explain terms briefly when first used if they may be unfamiliar
- Avoid unexplained jargon and acronym-heavy phrasing
- Keep wording direct, specific, and neutral

## Safety Rules

- Preserve technical meaning and factual content
- Do not invent commands, API behavior, or version claims
- Keep edits narrow and reversible
- Preserve existing project-specific terminology unless clearly inconsistent
- If uncertainty is high, prefer adding a short clarification request over guessing

## Procedure

## Validation Tool

Use the repo-local validation script before and after doc edits when possible:

- `test/check-docs` to validate all wiki markdown files
- `test/check-docs wiki/File.md` to validate one or more specific files
- `test/check-docs --fix wiki/File.md` only when a safe markdownlint auto-fix is appropriate

### 1. Confirm Target

Extract from user prompt:

- target markdown file(s) in `wiki/`
- constraints (tone, audience, preserve wording, max rewrite level)

If targets are missing, ask for paths before editing.

### 2. Confirm Depth

Extract from user prompt:

- desired depth mode:
  - syntax-only: fix markdown syntax/rendering issues only; do not rewrite wording or structure beyond what syntax requires
  - readability: include syntax fixes plus clarity and scanability edits without broad restructuring
  - full pass: include syntax, readability, structure normalization, terminology consistency, and broader doc cleanup

If depth is missing, default to readability and state that assumption.

### 3. Read And Diagnose

For each target file:

- If the scope is broad or unclear, run `test/check-docs` first to establish the current markdown baseline.
- Scan for syntax/rendering issues
- Identify readability pain points (dense blocks, weak headings, mixed terminology)
- Note risky sections where edits may alter meaning

### 4. Normalize Heading Hierarchy

Apply heading structure rules before deep rewrites:

- keep one logical top-level heading per file where appropriate
- avoid skipped levels (`##` directly to `####`) unless source constraints require it
- ensure sibling sections use consistent levels
- rename headings only when it improves clarity without changing meaning

### 5. Apply Syntax Fixes First

Fix rendering/correctness issues first, such as:

- broken heading levels
- malformed lists
- unclosed/misfenced code blocks
- malformed links/images
- inconsistent table delimiter rows
- accidental HTML/markdown mixing that breaks rendering

### 6. Apply Readability Improvements

Make editorial improvements while preserving meaning:

- split long paragraphs
- convert prose enumerations into lists when clearer
- improve section titles for scanability
- remove repetition and tighten wording
- align terminology within the same document

Apply tone constraints during edits:

- concise technical phrasing
- approachable wording for normal users
- no unexplained technical babble

### 7. Run Link Integrity Pass

Check and fix obvious link issues:

- malformed inline/reference links
- anchors that no longer match heading text after edits
- obvious relative-path mistakes in wiki cross-links

If link targets cannot be verified from repo context, keep the original target and flag it in the report.

### 8. Add Code Block Language Tags

For fenced code blocks:

- add language tags when confidently inferable (`bash`, `python`, `json`, `yaml`, etc.)
- correct clearly wrong tags
- leave tag blank only when language cannot be inferred safely

### 9. Run Completion Checks

Validate each edited file against this checklist:

- `test/check-docs` or `test/check-docs <file...>` passes for the affected scope
- markdown renders correctly
- heading hierarchy is logical
- code fences include language where known
- links/anchors are internally consistent and obviously valid
- no factual changes introduced
- tone is concise, technical, and approachable

### 10. Report Results

Return:

- files edited
- categories of changes made (syntax/readability/structure)
- any unresolved ambiguity or potential factual follow-ups

## Branching Guidance

- If the user asks minimal edits, still run heading normalization, link integrity checks, and code-block language tagging with minimal wording changes.
- If the user asks broad cleanup, run full pass including structure and terminology normalization.
- If a section appears technically outdated but cannot be verified from repo context, do not rewrite claims; flag it in the report.

## Pass Criteria

A successful pass means:

- requested wiki markdown files were edited
- syntax/rendering issues were corrected
- heading hierarchy was normalized
- link integrity pass was completed
- code block language tagging was applied where known
- readability clearly improved without changing intent
- output report summarizes edits and open follow-ups

More agent context in vladmandic/sdnext

20 other files this repository gives its agents.