octocode-documentation - Claude MCP Skill

# Octocode Documentation

Evidence-backed docs for humans and agents, written to the Google developer documentation style guide. Classify first. Gate writes. Prefer durable cross-refs over code dumps.

## Flow

`UNDERSTAND → RESEARCH → CLASSIFY → OUTLINE GATE → WRITE → STYLE → VERIFY`

UNDERSTAND names the deliverable, audience, and target paths. Compress when the request already names targets and type. Expand when claims need verification. A copyedit request starts at STYLE. Answer a single-term question ("is `allows you to` okay?") straight from `assets/google-word-list.tsv` — quote the guidance and stop.

## Rules

- Verify claims in the repository before asserting them. Invented commands, paths, APIs, and env vars are the one unrecoverable failure — omit or mark "Not verified in repository" instead.
- Pick one mode and load its routes before writing.
- Gate creates and overwrites unless the requester approved the targets this turn; a copyedit of a named file carries its own approval. Touch only the files they named — propose the rest.
- Apply the style defaults in `references/style-index.md` to every line you write or edit, and name the rule when you change someone else's wording.
- The style references are a snapshot of Google's guide, and every one links the pages it restates. IF someone disputes a rule, the pack doesn't carry it, or the wording carries risk (trademark, product name, legal claim, security claim) → THEN open the live page with a web tool, quote it with its URL, and fix the reference when it disagrees; say so when no fetch was possible.
- A style pass changes wording, not claims; a fact change goes back to RESEARCH.
- `AGENTS.md` is an index of links and non-obvious rules, not a content dump.
- Prefer durable pointers (module path, contract name, doc link) over line numbers and pasted code.
- One Diátaxis type per page; link siblings instead of mixing.
- IF the project documents its own style guide, or the repository already applies a convention consistently → THEN follow it and report the conflict instead of adding a second scheme.

Stop when: outline gate awaits answer; write+style+verify finishes; a word-list lookup answered the question; a missing fact makes the doc dishonest to write (otherwise mark "Not verified in repository" and continue); conventions conflict; user cancels.

## Workflows — the mode fixes the route order

| Mode | Deliverable | Route order |
|---|---|---|
| agent-docs | `AGENTS.md`, nested agent instructions, `CLAUDE.md` symlink | `modes.md` → `evidence-research.md` → `agents-md.md` → `agent-readable.md` → `write-verify.md` → `style-lint.mjs` |
| human-docs | README, tutorial, how-to, reference, explanation, runbook | `modes.md` → `evidence-research.md` → `diataxis.md` → `agent-readable.md` → `write-verify.md` → `style-lint.mjs` |
| adr | Architecture decision record | `modes.md` → `evidence-research.md` → `adr.md` → `write-verify.md` → `style-lint.mjs` |
| codebase-pack | Multi-file docs set | `modes.md` → plan the file set → gate once → per file: `diataxis.md` → `write-verify.md` → `style-lint.mjs` |
| style-pass | Edited text, or a style review report | `style-index.md` → the owning `style-*.md` → `style-lint.mjs` → `style-review.md` for a report someone else acts on |

## Routes — workflow references

| Phase | When | Read |
|---|---|---|
| CLASSIFY | Choosing mode or audience | `references/modes.md` |
| RESEARCH | Gathering or verifying repository facts | `references/evidence-research.md` |
| CLASSIFY | Choosing the Diátaxis type for human-docs, or reviewing one | `references/diataxis.md` |
| WRITE | Writing or updating agent instruction files | `references/agents-md.md` |
| WRITE | Recording a decision | `references/adr.md` |
| WRITE | Cross-refs, density, durability — read before the first line | `references/agent-readable.md` |
| OUTLINE GATE, WRITE, VERIFY | Outline gate, write steps, style pass, verify checklist | `references/write-verify.md` |
| STYLE | Any wording, formatting, or terminology question — maps every guide topic to its owner | `references/style-index.md` |

## Routes — style pack, grouped; `references/style-index.md` owns the per-topic map

| Ask | Read |
|---|---|
| Which reference owns this topic — every guide topic, one row each | `references/style-index.md` |
| Prose: tone, person, voice, tense, grammar, one specific word, abbreviations, jargon, translation, inclusive terms | `references/style-voice.md`, `references/style-grammar.md`, `references/style-words.md`, `references/style-abbreviations.md`, `references/style-global.md`, `references/style-inclusive.md` |
| Page shape: headings, lists, numbered steps, notices, tables, footnotes, figures, alt text | `references/style-structure.md`, `references/style-procedures.md`, `references/style-blocks.md`, `references/style-images.md` |
| Mechanics: bold/italic/code choice, capitalization, filenames, markup, punctuation, numbers, dates, units | `references/style-format.md`, `references/style-punctuation.md`, `references/style-numbers.md` |
| Technical text: code font, samples, command syntax, placeholders, example values, UI wording, link text | `references/style-code.md`, `references/style-cli.md`, `references/style-examples.md`, `references/style-ui.md`, `references/style-links.md` |
| Claims and reference text: time words, superlatives, product names, trademarks, third-party text, docstrings | `references/style-claims.md`, `references/style-api.md` |
| Producing a review someone else acts on, or checking a rule against the live guide | `references/style-review.md`, `references/style-sources.md` |

## Scripts and assets — what to run, when, and how

| Run | When | How it behaves |
|---|---|---|
| `scripts/style-lint.mjs <paths>` | At STYLE, before hand-reading prose | Markdown only. ERROR gates, WARN is mechanical, INFO needs judgment. One finding per rule per line; `--max-per-rule` caps per file (default 20); `--only`/`--skip` select rules; `--json` for machine output. Exit 1 on ERROR, or on WARN with `--strict`; 2 on bad usage |
| `scripts/style-lint.mjs --self-test` | After editing any rule | Lints built-in good/bad fixtures so a gate cannot go inert |
| `scripts/refresh-word-list.mjs --dry-run` | When the word list looks stale | Rebuilds `assets/google-word-list.tsv` from `developers.google.com`; it fetches even with `--dry-run`, and refuses to write a short parse |
| `assets/google-word-list.tsv` | Answering a single-term question | 597 guide entries with verdict and guidance; quote it and stop |
| `assets/google-style-pages.tsv` | Finding which reference owns a guide page, or its URL | All 69 pages as `slug`, `title`, `owner`, `url`; `grep -P "^tables\t"` answers ownership, and the URL is what you fetch to verify |

Suppression: `<!-- style-lint: ignore-file -->` skips a file found by recursion, `<!-- style-lint: ignore-line rule-id -->` mutes named rules on one line. Both are inert inside a code span, so a page can document them. Docstrings, HTML, and UI strings stay hand-checked.

## Related

- Pure code or repository evidence with no docs deliverable → `octocode-research`; authoring a `SKILL.md` → `octocode-skills`.
- Full multi-file pack → plan the file set, gate it once, then work file by file.
- Unclear mode → ask once: agent-docs / human-docs / adr / codebase-pack / style-pass. No Octocode → host search tools.
- Measuring whether this skill triggers and holds its routes → `octocode-graph-eval`; the runnable sensors here are `scripts/style-lint.mjs --self-test` (rules still fire) and `scripts/refresh-word-list.mjs --dry-run` (word-list drift).