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:
- This run already has a
release-research JSON report, and this feature appears there with needs_docs: true.
- 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).
- You called
get_docs_file for every docs path you will change and still have that exact content.
- 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):
{
"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. Prefer symbol. If you use quote, it must be an exact contiguous substring from get_product_source_file for that path at the tag. Paraphrases of issues, release notes, or diffs fail verification.
Steps
- 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.
- 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
- 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). The tool labels the PR release-watch-agent. A GitHub Action runs only on that label and syncs Linear status from the Closes 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
- 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 evidence verification fails
When create_linear_issue or create_draft_docs_pr raises that a symbol/quote was not found:
- Call
get_product_source_file for the cited path at the release tag (or the correct path from the research report / diff).
- Replace the bad item with a
symbol that appears in that file, or a short exact quote copied from the tool output.
- Retry the write tool once with the corrected
evidence_json.
- If you still cannot find a real citation in tagged source, skip shipping that feature and say so. Do not invent a quote.
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):
- Call
get_docs_file again for every path in the failed PR.
- Re-apply the same surgical edit on that fresh content.
- Retry
create_draft_docs_pr once with the new old_content / new_content.
- 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
## 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
1---2name: ship-docs-update3description: Open one Linear DOC ticket and one draft docs PR for a single documentation feature, grounded in product-source evidence.4metadata:5 source: https://skillmd.com/skills/langchain-ai/ship-docs-update6---78# Ship one docs update910Use 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.1112## One feature only1314- One Linear issue15- One draft pull request16- One focused branch17- No unrelated edits in the same PR1819If 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.2021## Preconditions (required)2223Before calling any write tool:24251. This run already has a `release-research` JSON report, and this feature appears there with `needs_docs: true`.262. 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).273. You called `get_docs_file` for every docs path you will change and still have that exact content.284. 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):2930```json31{32 "source_repo": "langchain-ai/deepagentsjs",33 "source_tag": "deepagents@1.14.2",34 "items": [35 {36 "path": "libs/deepagents/src/middleware/foo.ts",37 "symbol": "offloadBinaryContent"38 }39 ]40}41```4243Each item needs `path` plus `symbol` or `quote`. Empty evidence is rejected. Prefer `symbol`. If you use `quote`, it must be an exact contiguous substring from `get_product_source_file` for that path at the tag. Paraphrases of issues, release notes, or diffs fail verification.4445## Steps46471. 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.482. Create the Linear issue with `create_linear_issue`:49 - `team_key="DOC"`50 - Title: concise, feature-scoped (for example "Document OpenWiki Copilot CLI integration")51 - Description: release tag, why docs must change, files to touch, acceptance criteria52 - Pass `product`, `release_tag`, and `evidence_json`53 - The tool assigns the issue to the Linear API key owner (Naomi) automatically543. Create the draft PR with `create_draft_docs_pr`:55 - Branch: `docs/<product>-<version>-<feature-slug>`56 - Title matches the issue scope57 - Body must include a `## Linear` section with `Closes [DOC-N](<issue url>)` (markdown hyperlink). The tool labels the PR `release-watch-agent`. A GitHub Action runs only on that label and syncs Linear status from the Closes line (draft open → In Progress, ready for review → In Review, merged → Done, closed unmerged → Canceled), so the `Closes DOC-N` link is required.58 - Pass the same `evidence_json`59 - Pass `product` so language-fence validation uses the registry scope (`python` / `js` / `shared`)60 - `files_json` is a JSON array of `{ "path": "...", "old_content": "...", "new_content": "..." }`61 - `old_content` must be the exact string returned by `get_docs_file` (empty string only for a brand-new file)62 - Keep the edit surgical: the tool rejects diffs that rewrite too much of an existing page or change the other language fence634. 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`.6465## If evidence verification fails6667When `create_linear_issue` or `create_draft_docs_pr` raises that a symbol/quote was not found:68691. Call `get_product_source_file` for the cited path at the release tag (or the correct path from the research report / diff).702. Replace the bad item with a `symbol` that appears in that file, or a short exact `quote` copied from the tool output.713. Retry the write tool once with the corrected `evidence_json`.724. If you still cannot find a real citation in tagged source, skip shipping that feature and say so. Do not invent a quote.7374## If `create_draft_docs_pr` fails7576The 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):77781. Call `get_docs_file` again for every path in the failed PR.792. Re-apply the same surgical edit on that fresh content.803. Retry `create_draft_docs_pr` once with the new `old_content` / `new_content`.814. 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.8283## PR body template8485```md86## Summary87- <one sentence on the docs change>88- Triggered by <product> <release tag>8990## Linear91Closes [DOC-<number>](<issue url>)9293## Source evidence94- Repo: `<owner>/<repo>`95- Tag: `<release tag>`96- `<path>`: `<symbol or short quote>`9798## Test plan99- [ ] Preview the changed pages100- [ ] Confirm claims against the cited product source at the tag101- [ ] Run `make lint_prose FILES="<changed mdx paths>"` when possible102```103104The write tools append a Source evidence section when the body omits one. Prefer writing it yourself so the citations stay next to the summary.105106## Do not107108- Bundle multiple features into one issue or PR109- Ship before calling the `release-research` subagent in this run110- Ship a feature that is not in the research report111- Draft docs without reading the docs repo `AGENTS.md` in this run112- Draft from release notes without reading product source at the tag113- Pass full page contents invented from memory (always start from `get_docs_file`)114- Omit `old_content` or invent a base that does not match `main`115- Ship without `evidence_json` that points at product source at the tag116- Modify `docs-release-watch/` in the docs PR117- Put secrets, tokens, or `.env` contents into issues or PRs118- Mark the PR ready for review; leave it as a draft119- Edit `:::python` sections for a JS-only feature, or `:::js` for a Python-only feature120- Claim success without a tool-returned Linear URL and PR URL