ship-docs-update

# Ship one docs update Use this skill in **phase 2** when you are ready to create tracking and a draft PR for exactly one feature from a `release-research` report. ## One feature only - One Linear issue - One draft pull request - One focused branch - No unrelated edits in the same PR If the research report lists multiple features, call this workflow once per feature. Do not invent features that research did not list. If you notice unrelated changes that should be made, leave them for a later research pass instead of shipping them now. ## Preconditions (required) Before calling any write tool: 1. This run already has a `release-research` JSON report, and this feature appears there with `needs_docs: true`. 2. You called `get_docs_file` on `AGENTS.md` in `langchain-ai/docs` and read it in full. That file is the style and structure authority for the PR. Do not confuse it with `/memories/agent/AGENTS.md` (hot memory status only). 3. You called `get_docs_file` for every docs path you will change and still have that exact content. 4. You prepared `evidence_json` from the research report's `evidence` object (the write tools re-fetch each path at the tag and refuse if the citation is missing): ```json { "source_repo": "langchain-ai/deepagentsjs", "source_tag": "deepagents@1.14.2", "items": [ { "path": "libs/deepagents/src/middleware/foo.ts", "symbol": "offloadBinaryContent" } ] } ``` Each item needs `path` plus `symbol` or `quote`. Empty evidence is rejected. ## Steps 1. Edit surgically from the `get_docs_file` content, following the docs repo `AGENTS.md` (frontmatter, voice, no markdown in `description`, Tabler icons, sentence-case headings, no contractions, no first person, language fences, navigation rules, and the rest of that file). Change only the sections needed for this feature. Do not rewrite the rest of the page. Do not invent content for the other language fence. 2. Create the Linear issue with `create_linear_issue`: - `team_key="DOC"` - Title: concise, feature-scoped (for example "Document OpenWiki Copilot CLI integration") - Description: release tag, why docs must change, files to touch, acceptance criteria - Pass `product`, `release_tag`, and `evidence_json` - The tool assigns the issue to the Linear API key owner (Naomi) automatically 3. Create the draft PR with `create_draft_docs_pr`: - Branch: `docs/<product>-<version>-<feature-slug>` - Title matches the issue scope - Body must include a `## Linear` section with `Closes [DOC-N](<issue url>)` (markdown hyperlink). A GitHub Action syncs Linear status from that line (draft open → In Progress, ready for review → In Review, merged → Done, closed unmerged → Canceled), so the `Closes DOC-N` link is required. - Pass the same `evidence_json` - Pass `product` so language-fence validation uses the registry scope (`python` / `js` / `shared`) - `files_json` is a JSON array of `{ "path": "...", "old_content": "...", "new_content": "..." }` - `old_content` must be the exact string returned by `get_docs_file` (empty string only for a brand-new file) - Keep the edit surgical: the tool rejects diffs that rewrite too much of an existing page or change the other language fence 4. Record the Linear URL and PR URL in product memory before starting the next feature. Only treat the ship as successful when both tools returned a `url`. ## If `create_draft_docs_pr` fails The tool rebases stale `old_content` onto live `main` when the changed hunks still apply. When it still fails (for example `old_content does not match` / could not be rebased): 1. Call `get_docs_file` again for every path in the failed PR. 2. Re-apply the same surgical edit on that fresh content. 3. Retry `create_draft_docs_pr` once with the new `old_content` / `new_content`. 4. If the retry also fails, call `note_ship_failure_on_linear_issue` with the DOC identifier and a short reason. That appends a **Ship failure** section (and the LangSmith run URL when available) to the issue so a human can debug. Leave the issue open. Do not claim the feature shipped. ## PR body template ```md ## Summary - <one sentence on the docs change> - Triggered by <product> <release tag> ## Linear Closes [DOC-<number>](<issue url>) ## Source evidence - Repo: `<owner>/<repo>` - Tag: `<release tag>` - `<path>`: `<symbol or short quote>` ## Test plan - [ ] Preview the changed pages - [ ] Confirm claims against the cited product source at the tag - [ ] Run `make lint_prose FILES="<changed mdx paths>"` when possible ``` The write tools append a Source evidence section when the body omits one. Prefer writing it yourself so the citations stay next to the summary. ## Do not - Bundle multiple features into one issue or PR - Ship before calling the `release-research` subagent in this run - Ship a feature that is not in the research report - Draft docs without reading the docs repo `AGENTS.md` in this run - Draft from release notes without reading product source at the tag - Pass full page contents invented from memory (always start from `get_docs_file`) - Omit `old_content` or invent a base that does not match `main` - Ship without `evidence_json` that points at product source at the tag - Modify `docs-release-watch/` in the docs PR - Put secrets, tokens, or `.env` contents into issues or PRs - Mark the PR ready for review; leave it as a draft - Edit `:::python` sections for a JS-only feature, or `:::js` for a Python-only feature - Claim success without a tool-returned Linear URL and PR URL