Migrate Feature Page

Migrate Feature Page

Used during the Infrahub docs revamp to migrate one feature page (Layer 2 content under a Features sub-category) — or an entire docs section — from a topic + guide pair to a cleaner structure. Each migration gets its own branch and PR for scoped review.

Reference precedent

The Groups feature was the first single-feature migration. Files to reference when in doubt:

• docs/docs/groups/index.mdx — hub
• docs/docs/groups/*.mdx — spokes
• docs/docs/academy/tutorials/groups.mdx — preserved tutorial
• Confluence: Docs Revamp — Groups Before/After Content Diff

For section-wide restructures, look for a per-section recommendation page on Confluence (e.g. Branches & Change Control Recommendations) — these capture the team-approved structure before migration starts.

Inputs the user provides

• Feature or section name (e.g. "Profiles", "Resource Manager", "Webhooks", "Branches & Change Control section")
• Recommendation doc (Confluence link) for section-wide migrations — confirms the approved structure
• Optional notes about this feature/section

Inputs the skill derives

• Topic file(s): docs/docs/topics/<slug>.mdx
• Guide file(s): docs/docs/guides/<slug>.mdx
• Sidebar location: usually Features > <Section> in docs/sidebars.ts
• Inbound links from other docs (via grep)

Workflow

Use TodoWrite to track. Stop and confirm with the user at every ★ gate. For section-wide migrations, also see Recommendations for large or section-wide migrations at the bottom — apply those on top of the standard workflow.

Meta-rule: never recommend silently. When the spec-review (Step 2.5) or implementation surfaces additional changes beyond what the recommendations doc already states — like merging two pages into one, adding a missing spoke, renaming a label, restructuring a sub-category — present the recommendation to the user with rationale and wait for a decision before implementing. The recommendations doc is the canonical spec; deviations get explicit approval, not silent application.

Step 1 — Pre-flight

• Verify current branch is demo/groups-diataxis-example (the consolidated parent branch). If not, switch.
• Run git status -s. Any uncommitted changes? Stop and ask user how to handle them before creating a new branch.
• Create new branch:
  • Single-feature migration: docs/migrate-<feature-slug> (e.g. docs/migrate-profiles)
  • Section-wide migration: docs/migrate-<section-slug> (e.g. docs/migrate-branches-and-change-control)
• Confirm the local serve and build work as a baseline.

Step 2 — Audit existing content ★

Read the source files completely:

• docs/docs/topics/<slug>.mdx
• docs/docs/guides/<slug>.mdx
• For section-wide migrations: read every page that's part of the section, not only one feature

Produce a compact summary covering:

• Topic page(s): section headings, line count, observations on quality / gaps
• Guide page(s): section headings, line count, is it tutorial-shaped? Tutorial-shape signals: Step 1/2/3 headings, single running example used throughout, "Next steps" closer, linear narrative
• Inconsistencies / gaps — flag for user review (don't silently fix)
• Inbound cross-links — grep -rln 'topics/<slug>\|guides/<slug>' docs/docs/ (excluding the files themselves and other obvious matches). List which other docs reference them.

★ Gate: present the audit to the user. Wait for confirmation before proceeding.

Step 2.5 — Spec review against skill rules ★ (when a recommendations doc exists)

When the user provides a Confluence recommendations doc (typical for section-wide migrations), the doc replaces Steps 2 and 3 as the planning artifact. But the doc may have gaps — review it critically against the skill's decision rules before implementing.

Read the doc end-to-end. Then run this checklist against the proposed structure:

• Topic+guide pairs being treated as separate moves. A topic file + a guide file describing the same single feature → single-page-merge candidate per the decision rules below. Don't preserve the split.
• Shared name roots that suggest merging. If multiple files share a name root (e.g. branch-synchronization + selective-branch-sync) AND describe related procedural work, they're merge candidates. Treat them as one feature unless there's a specific reason to keep them separate.
• Hub categories without a clickable link. Every category that becomes a hub in sidebars.ts must have link: { type: 'doc', id: '<feature>/index' }. Without that, the category caret expands but the label is dead. Confirm the doc specifies an explicit hub for each new category.
• Tutorial-shaped guides not being extracted. Run the tutorial-shape check (Step 1/2/3 headings, single running example, narrative arc) on every guide in the spec. If a guide is tutorial-shaped but the doc says "keep here," ask whether to extract or reframe.
• Missing common spokes. When converting a feature to hub+spokes, common operations (create, update, delete, query, etc.) typically each get a spoke. If the doc lists 3 spokes but obvious operations are missing, flag it.
• Legacy (Topic) / (Guide) sidebar labels. If the new sidebar still has these suffixes, that means the migration is half-done — those labels should disappear when files convert to hub+spokes or single-page merge. Check.
• Broken cross-link patterns. When a feature moves into a sub-section (e.g. Git Integration nesting under Branches & Change Control), pages from that sub-section reference each other via paths that may need updating.

Per the meta-rule: every finding gets presented to the user with rationale, not silently applied. The user updates the doc, then you implement against the updated spec.

★ Gate: present spec-review findings. User decides which to add to the spec, which to leave as-is. Once decisions land, the user (or you, on their behalf) updates the recommendations doc to reflect the final spec. Then proceed to Step 4.

Step 3 — Pattern decision ★ (when no recommendations doc exists)

When no doc exists (typical for single-feature migrations), recommend a pattern based on the Step 2 audit. Get user approval before creating files.

Decision rules:

Default: single-page merge unless the feature genuinely warrants more complexity.

Tutorial scenario-shape test. If the chosen pattern preserves an Academy tutorial (Tutorial extraction or Split), apply this check before keeping it: read the source guide and ask "does this teach a coherent end-to-end scenario someone would actually want to learn — routers/switches at scale, modeling a service, onboarding a new team — or is it the same content as the existing guide with sequence numbers stuck on it?" If the latter, the tutorial is feature-oriented, not scenario-oriented; flag it to the user and recommend dropping the tutorial from this PR with a follow-up entry on the Open Questions Confluence page describing the scenario rewrite. Do not ship feature-oriented tutorials — they don't earn their sidebar slot. (Precedent: the Profiles tutorial was dropped on PR #9114 review for exactly this reason.)

★ Gate: present the recommended pattern with rationale, including the tutorial scenario-shape verdict if applicable. User approves or chooses different.

Step 4 — Create new files

Follow the chosen pattern. For section-wide migrations, do this one feature at a time with a build verification between each — see the section-wide recommendations below.

Match the interfaces shown in the existing guide / tutorial. Before writing any how-to or spoke content, look at the existing guide and tutorial for that feature. They use Tabs to show the same task across the UI, Python SDK, and GraphQL — that ordering reflects how users actually interact with the feature (UI primary, SDK via generators, GraphQL last). When you create the new how-to spokes, preserve that same set of interface tabs and reuse the same running example. Do not reduce a multi-interface task to GraphQL-only because it's faster to write — the existing guide content is the source of truth for which interfaces matter and what the canonical UI navigation steps look like. If a new task isn't covered in the existing guide, mirror the interface set used elsewhere in the same feature's docs.

Voice and tone

Match the voice of the canonical Infrahub docs and the conventions of well-regarded open-source documentation (Stripe, Tailwind, FastAPI, Docusaurus). The reader knows they are reading a docs page — do not narrate that fact at them.

Do not refer to "this page", "this section", or "this document". Those describe the layout/medium, not the content — the reader knows they are reading a page, and headers and the URL already do that wayfinding work. Banned phrases:

• ❌ "This page covers …" / "This page applies to …" / "This page collects …"
• ❌ "This document explains …" / "This section describes …"
• ❌ "On this page you'll find …"

Instead, just state what is true. If you genuinely need to direct the reader to nearby content, use "below" or "here":

• ✅ "The steps below cover the canonical workflow for creating one."
• ✅ "The patterns below come from real-world experience …"
• ✅ "Standard groups only — Generator and Query groups …"

"This guide" and "this tutorial" are fine — those refer to the functional kind of document (a guide guides you, a tutorial teaches you). They are genre markers, not layout descriptors. Use them when the genre framing actually helps the reader:

• ✅ "This guide shows how to connect a remote repository …"
• ✅ "In this guide, we'll walk through three approaches and when to pick each."
• ✅ "By the end of this tutorial you will have built, deployed, and validated …"
• ✅ "This tutorial uses BuiltinTag objects so you can follow along without any special schema."

When the legacy source content uses the banned "this page / this section / this document" phrases (it often does), rewrite them on extraction — don't carry them forward. The new file is shipping under the new structure; legacy slop doesn't get a free pass just because it was already there. Legacy "this guide" / "this tutorial" usage on a guide or tutorial page is fine to keep.

Tutorial opener convention. Academy tutorials use ONE consolidated opener — see academy/tutorials/groups.mdx and academy/tutorials/build-a-check.mdx for the precedent:

• ✅ "By the end of this tutorial you will have built, deployed, and validated …" — one paragraph combining the framing with the outcomes, then the body

Do not use both a "This tutorial walks you through …" intro AND a separate "By the end of this tutorial you will:" bullet list — that's redundant. Pick one paragraph that does both jobs.

Other voice rules (carryover from project house style — apply to any new prose you author):

• No "Let me walk you through …" / "Let's get started …" — drop the meta and start the work
• No apologies, compliments, or filler ("Great!", "Awesome!", "Now you've successfully …")
• No "simply", "easily", "just", "simple", "easy" — they imply the reader is failing if it isn't simple for them (also caught by the AGENTS.md word check at PR time, but cheaper to avoid up front)
• Active voice, present tense, second person ("you create a Generator …", not "a Generator can be created by you")

Banned jargon — words that don't earn their place:

• ❌ "canonical" (as in "the canonical workflow", "the canonical way", "the canonical pattern") — implies "the official/authoritative one," which is meaningless when there's only one workflow being described. Drop the qualifier or use a plain alternative.
  • ❌ "The steps below cover the canonical workflow for creating a Generator."
  • ✅ "The steps below cover how to create a Generator."
  • ✅ "The steps below cover the recommended workflow." (when "recommended" actually adds information — e.g. there is a known alternative being deprecated)
• Watch for similar empty qualifiers in your own writing: "proper", "correct", "right" (as in "the proper way to do X"). If there's only one way, just describe it. If there are multiple ways, name them and explain trade-offs.

When in doubt, ask: would this sentence read better with the qualifier removed? If yes, remove it.

Single-page merge (Computed Attributes precedent — PR #9120):

• Create docs/docs/<feature>/index.mdx — combine topic content (top) and guide content (rewritten below as how-to sections)
• Drop "Step 1/2/3" wording from headers; use action-named section headers ("Configure your X", "Verify your X")
• Numbered procedural lists inside sections stay numbered when sequence matters
• Replace running examples with placeholders like <group-name>, <object-id>
• Original docs/docs/topics/<slug>.mdx and docs/docs/guides/<slug>.mdx: leave on disk during iteration (legacy URLs work); deleted in cleanup PR
• Sidebar entry: { type: 'doc', id: '<feature>/index', label: '<Feature>' } — the merged page IS the canonical sidebar entry; no folder/category needed

Why folder + index.mdx for single-page merges too? Even when there's only one page, using <feature>/index.mdx keeps URLs stable (/<feature>/) regardless of future restructures. If the page later grows into hub+spokes, no file move is needed — only adding sibling spokes. Computed Attributes shipped this way; it's the established pattern.

Hub + spokes (Groups / Profiles precedent):

• Hub at docs/docs/<feature>/index.mdx — topic content only. Do NOT add a "Common tasks" or "Deeper concepts" link list — the spokes already appear in the sidebar when the user is on the hub, so a body link list is redundant clutter. A "Learn by doing" body link to an Academy tutorial is OK because the tutorial lives in a different sidebar section.
• Spokes at docs/docs/<feature>/<task>.mdx — one per task. Each spoke ends with a brief ## Next section pointing to adjacent spokes (always Next, not Related — mixed heading names across a spoke set is a recurring review comment).
• Optional concept spoke at docs/docs/<feature>/<concept>.mdx for substantial deep-dive content (e.g. priority and inheritance) when it's a frequently-referenced topic and would otherwise bloat the hub.
• Optional Academy tutorial at docs/docs/academy/tutorials/<feature>.mdx

Critical: hub categories must have a clickable link. In sidebars.ts, every category that becomes a hub must include link: { type: 'doc', id: '<feature>/index' }. Without this, the category caret expands but the label itself is dead — clicking "Profiles" or "Branches" does nothing. The Groups, Profiles, and Branches categories all have this; it's a recurring bug to forget. Verify after writing the sidebar entry.

Tutorial extraction:

• Move guide to docs/docs/academy/tutorials/<slug>.mdx
• Preserve original title (e.g. "How to organize objects with groups" stays the same)
• Reframe as tutorial: add "By the end of this tutorial you will…" preamble; "What you learned" closer
• Topic page may need light edits if it referenced the old guide

Step 5 — Update sidebar

Modify docs/sidebars.ts. Replace the old topic+guide pair entries with the new structure. Use the small color-matched caret (already styled in custom.css) for nested categories where used.

Step 6 — Build + verify

cd docs && npm run build

Fix any broken doc IDs or links. Run npm run serve to visually check.

Step 7 — Add redirects-pending file

Each migration drops a YAML file in docs/redirects-pending/ recording the URL changes the migration introduces. The file has three sections — redirects (legacy → new), new pages introduced (canonical URLs for cross-reference), and cross-links in other files that need updating at cleanup. At end-of-Phase-2 (cleanup PR), all files are aggregated. See docs/redirects-pending/README.md for the schema.

Create docs/redirects-pending/<feature-or-section-slug>.yml:

---
feature: <Feature Name or Section Name>
pr: TBD
description: |
  Brief explanation of what changed and why these redirects exist.

# Legacy URLs that will redirect to new locations
redirects:
  - from: /docs/<old-path>
    to: /docs/<new-path>

# Net-new pages introduced by this migration (canonical URLs for cross-reference)
new_pages:
  - path: /docs/<feature>/
    title: <Feature> (hub)
  - path: /docs/<feature>/<task>
    title: <Task title>

# Internal cross-link references in OTHER files that point at legacy paths
# (will resolve via redirect at runtime but should be updated to new paths at cleanup)
cross_links_to_update:
  - file: docs/docs/topics/some-other-page.mdx
    line: 42
    current: ../topics/<slug>
    should_be: ../<feature>/

Common patterns for the redirects section:

• Hub + spokes (Groups / Profiles precedent) — both legacy URLs redirect to the new hub:
  • /docs/topics/<feature> → /docs/<feature>/
  • /docs/guides/<feature> → /docs/<feature>/
• Single-page merge — guide URL redirects to canonical topic:
  • /docs/guides/<feature> → /docs/topics/<feature>
• Tutorial extraction only — guide URL redirects to topic; tutorial URL is new (no redirect needed):
  • /docs/guides/<feature> → /docs/topics/<feature>

Update docs/redirects-pending/README.md "Files in this folder" table to add the new entry.

Step 8 — Cross-reference scan

• Run grep -rln '<feature-slug>' docs/docs/ to find inbound references to the legacy paths.
• For each, identify whether the page actually mentions / depends on the migrated feature (vs a path coincidence).
• For pages in other sections that should reference this feature in CONTENT (not sidebar), add an entry to the Confluence Open Questions page under "Surface cross-section content via prose." Do NOT modify those other-section pages in this PR — out of scope.
• For pages in other sections that have stale Markdown links to legacy paths (will resolve via redirect at runtime but should be updated to new paths at cleanup): add an entry to the redirects-pending file's cross_links_to_update section with file, line, current link target, and should_be link target. This gives the cleanup PR a complete inventory.
• For internal cross-links within the feature itself (e.g. spokes referencing each other, hub referencing spokes) that are now stale, fix them in this PR.