--- name: docs-restructure description: Restructure documentation that spans several pages. Covers splitting a page that has grown too long, moving sections between pages, retiring a page, and fixing a topic documented in two places at once. Use when asked to streamline, simplify, consolidate, or reorganize docs, or when a page review keeps producing edits without the page getting shorter. --- # Restructure docs across pages The failure this skill prevents: an agent asked to "streamline this page" reorders its sections, collapses them into accordions, retitles them, and tabulates them, thirty times over, while the page gets longer. The page was never the problem. Three of its sections already existed on sibling pages. Single-page skills cannot see that. `add-docs-page` owns one page's lifecycle and `docs-edit` owns one page's diff. This skill owns the question they cannot ask: **is this content on the right page at all?** `AGENTS.md` holds the navigation map, the style guide, and the frontmatter rules. This skill covers the procedure around them and does not repeat them. ## Step 1. Establish the page family A page almost never lives alone. Find its siblings before reading it closely: ```bash ls src/langsmith/llm-gateway*.mdx # a flat-file family ls src/oss/deepagents/ # a directory family grep -n '"langsmith/llm-gateway' src/docs.json # what the nav groups together ``` The nav grouping is the better signal when the two disagree: pages a reader moves between are the pages whose content can be confused. Then list every heading in the family, so you are working from the whole shape rather than one file: ```bash grep -n '^## ' src/langsmith/llm-gateway*.mdx ``` ## Step 2. Build a duplication map before writing anything This is the step that does the work. For each H2 in the page you were asked to fix, search the rest of the family for the same content: ```bash grep -rn 'LANGSMITH_GATEWAY' src/langsmith/ --include=*.mdx grep -rn 'Use a regional gateway' src/ --include=*.mdx ``` Search for the distinctive noun, env var, or endpoint in the section, not for its heading. Duplicated content is usually retitled, which is why heading searches miss it. Record for each section: **does this topic already live somewhere else, and where?** Two copies that have drifted apart are the strongest finding available. It means no page owns the topic, so both copies are edited independently and readers get contradictions. In one real case the quickstart claimed TypeScript support for three providers while the sibling page said "Python only." Report the map before editing anything. "Three of these six sections duplicate `llm-gateway-api-formats`" is the finding. The restructure is downstream of it. ## Step 3. Assign one home per topic For each topic in the map, pick the single page that should own it: - **Prefer a page that already exists.** A new page is warranted when the topic has no home and does not fit an existing one, not when it merely needs somewhere to go. - **Prefer the page a reader would search for**, not the page the content happens to sit on. - **Keep the most-linked URL.** Check before choosing, because inbound links decide which file survives a merge of two pages: ```bash grep -rn '(/langsmith/llm-gateway)' src/ --include=*.mdx | wc -l ``` Folding content *into* the well-linked page and retiring the other one is usually cheaper than the reverse. ## Step 4. Cut, do not relocate A section that duplicates a sibling gets **deleted** and replaced with one sentence pointing at the owner. It does not get moved, collapsed into an accordion, or shortened in place. An accordion still costs the reader the decision of whether to open it. Content that has no home yet moves. Content that has one is already written. When you delete a section whose facts differ from the sibling's, the difference is a bug in one of them. Resolve it against the source before deleting, or you silently pick a winner. See `docs-edit` for the verification procedure. ## Step 5. Mechanics Retiring, renaming, or creating a page means navigation entries, redirects, and inbound links. `add-docs-page` covers all of it, including the anchor-stability and snippet traps. Follow it rather than improvising here. Two additional things a restructure breaks that a single-page edit does not: - **Section anchors other pages link to.** Moving a section moves its anchor. Grep for `#the-anchor` across `src/` before the move and repoint every hit. A `` or `` can carry an explicit `id` to preserve a landing spot that is no longer a heading. - **Cross-page pointers that now point at the wrong page.** After moving a topic, the sibling pages that used to reference its old location need repointing, not just the page you edited. ## Step 6. Verify ```bash make lint_prose FILES="" make build make broken-links-with-anchors python3 scripts/check_removed_pages_redirects.py --base-ref origin/main src/docs.json ``` Read `broken-links-with-anchors` by skipping to the `⎿` lines; those are the only real failures. Compare the count against the same command on `origin/main` so a pre-existing baseline is not read as a regression. Then review the prose with the `docs-review` skill, scoped to the files this pass changed. ## Step 7. Report what moved State, per page, what was **deleted**, what **moved**, and what was **added**, with before and after line counts. A restructure that cannot show a page getting shorter has not restructured anything, and the line counts are what show the reviewer whether it did. Name what you deleted rather than only what you wrote. A reviewer who asked for a shorter page needs to see the cuts to agree with them. ## Scope Stay inside the page family named in the request. A restructure surfaces adjacent problems: stale model IDs, legacy version numbers, and the same duplication one directory over. Report them, and **ask before widening the sweep.** Fixing sixteen instances across a page family is a reasonable follow-on inside one pull request. Fixing six hundred across the corpus is a separate pull request and probably a tracked issue, because some instances are deliberate and some live in generated files. ## Checklist - [ ] Page family established from `src/docs.json`, not guessed from filenames. - [ ] Duplication map built and reported before any edit. - [ ] One owner chosen per topic; most-linked URL identified before merging pages. - [ ] Duplicated sections deleted and replaced with a pointer, not relocated. - [ ] Conflicting facts between copies resolved against source, not by picking one. - [ ] Redirects, nav entries, inbound links, and section anchors all updated. - [ ] Verification commands run, `⎿` count compared against `origin/main`. - [ ] Report gives per-page before and after line counts. - [ ] Anything outside the page family reported, not swept, unless asked.