write-internal-docs

# Write Internal Docs

Write a doc for `.internal-docs/` (private repo `browseros-ai/internal-docs`), as Markdown plus a self-contained HTML sibling, and open a PR. The subject is whatever the user names ("/write-internal-docs nightly signing") or, on a feature branch with no topic, the branch's diff. Companion to `ask-internal`: that skill reads internal-docs, this one writes it. Supersedes the older personal `document-internal` flow.

**Announce at start:** "I'm using the write-internal-docs skill to draft and land an internal doc."

## Hard rules — never do these

- NEVER write inside the user's `.internal-docs/` checkout. All writes happen in the work clone.
- NEVER push to internal-docs `main`. Feature branch + PR only.
- NEVER touch the OSS repo's `.gitmodules` or submodule pointer. The sync workflow moves it after merge.
- NEVER `git add -A` or `git add .` in the work clone. Specific paths only.
- NEVER run a clone-touching command without the guard `[ -d "$CLONE/.git" ]` — a missing clone must fail loudly, not fall through to the OSS repo.
- NEVER fabricate content for empty template sections. Empty stays empty.
- NEVER hand-edit an `.html` sibling. The `.md` is the source of truth; regenerate the HTML from it.
- NEVER cite a file or line number you have not actually read.

## Voice rules

Every sentence of doc output follows these. Step 4 enforces them.

- Lead with the point. First sentence answers "what is this?"
- Concrete nouns. Name files, functions, commands. Not "the system".
- Short sentences, average under 20 words. Active voice. No em dashes.
- Banned words: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant, leverage, utilize.
- No filler intros ("This document describes..."). Start with the substance.
- Feature notes: body 60 lines max. Architecture and design docs have no cap.

## The work clone

Shell state does not survive between Bash calls, so the clone lives at a deterministic path that every snippet re-derives — never `mktemp`, never a cleanup `trap` (it would fire when the first call exits and delete the clone mid-workflow):

```bash
CLONE="${TMPDIR:-/tmp}/internal-docs-<slug>"
```

Substitute the literal slug. Every later snippet starts with this line plus the guard `[ -d "$CLONE/.git" ] || { echo "work clone missing: $CLONE"; exit 1; }`. Cleanup is an explicit `rm -rf "$CLONE"` in Step 8, never automatic.

## Workflow

### Step 0: Pre-flight

```bash
if git submodule status .internal-docs 2>/dev/null | grep -q '^-'; then
  echo "internal-docs submodule not initialized. Run: git submodule update --init .internal-docs"
  exit 0
fi
[ -d .internal-docs ] && [ -n "$(ls -A .internal-docs 2>/dev/null)" ] || {
  echo ".internal-docs/ missing or empty. Submodule not configured?"; exit 0; }
gh auth status >/dev/null 2>&1 || { echo "gh not authenticated. Run: gh auth login"; exit 0; }
git ls-remote git@github.com:browseros-ai/internal-docs.git HEAD >/dev/null 2>&1 || {
  echo "Cannot reach internal-docs over SSH. Check your keys: ssh -T git@github.com"; exit 0; }
```

**Done when:** submodule present, `gh` authenticated, and SSH reaches internal-docs — or the skill stopped with the fix command.

### Step 1: Scope the doc

Establish four facts. Take them from the user's invocation; derive what you can before asking.

1. **Subject** — the specific thing the user named, or the current branch's diff (`git diff main...HEAD --stat` plus the PR body) when invoked from a feature branch with no topic. For a named subject, research it first: grep the codebase and `.internal-docs/`, read the files that own it. If a doc on it already exists, this run updates that doc instead of creating a twin.
2. **Type and target dir** — `setup/` (runbook), `features/` (shipped feature), `architecture/` (cross-cutting subsystem), `designs/` (decision or RFC). Branch heuristics: `feat/*` → features, `rfc/*`/`design/*` → designs. Unclear → ask one question.
3. **Filename** — short kebab-case slug. Features prefix `YYYY-MM-`, designs prefix `YYYY-MM-DD-` (matches the existing tree).
4. **Owner** — GitHub handle, default `gh api user --jq .login`.

**Done when:** all four are stated and the target path (`<dir>/<file>.md`) is printed.

### Step 2: Zoom out

Before drafting, go up one layer of abstraction. Map the territory the doc covers: the relevant modules, their callers, and how data flows between them, in the project's domain vocabulary. Read the real files; tie every named module to a path.

This map becomes the doc's first body section, before any detail. A reader who knows nothing about the area gets the shape first, then zooms in.

**Done when:** you can draw the map (ASCII or mermaid, plus 2-4 sentences) and every box in it names a real path you read.

### Step 3: Draft the Markdown

Read the matching template from `.internal-docs/_templates/` (`feature-note.md`, `architecture-note.md`, `design-spec.md`; setup runbooks follow the shape of existing `setup/` docs). Fill it:

- The zoom-out map from Step 2 leads the body, as the first section after the frontmatter (for feature notes, it opens "How it works").
- Every factual claim cites `path/to/file.ts:line` you actually read.
- Sections with nothing real to say stay empty.

**Done when:** the draft matches the template's sections, opens with the map, and every claim carries a citation.

### Step 4: Voice check

Scan the draft against the voice rules: em dashes, banned words, sentence length, filler intros, the 60-line cap for feature notes. Rewrite offending sentences in place, max 3 passes. Still failing after 3 → stop and report which rules are violated.

**Done when:** a scan finds zero violations, or the failure is reported.

### Step 5: Clone, write, render HTML

Create the work clone (user's checkout stays clean):

```bash
CLONE="${TMPDIR:-/tmp}/internal-docs-<slug>"
rm -rf "$CLONE"