product-term-rename

Rename dbt product terms across the docs, following the finalized naming convention. Mechanical work is deterministic (bundled scripts); the LLM is spent only on prose that needs editorial judgment.

Core principle — be SPECIFIC, don't collapse

Each product renders as a distinct term so a reader can always tell which product a sentence refers to. Do not collapse everything to bare dbt — that makes contrasting sentences render identically ("removed in dbt and in dbt") and hides the specific-vs-generic decision. Instead, constants render the specific product, and dbt (generic) is applied deliberately, only where a statement is genuinely product-agnostic.

The naming rules this skill enforces

1. Fusion / dbt Fusion engine → dbt v2.
2. dbt Core → dbt v1 (this is the default for dbt Core / the core constant).
3. Genuinely product-agnostic statements (true of dbt regardless of version) → dbt — applied deliberately, e.g. by switching the occurrence to <Constant name="dbt" />.
4. Inline v1/v2; dbt v1/dbt v2 only in a header or at the start of a sentence.
5. Scope: exclude blogs and release notes; include upgrade guides; everything else in website/docs/** and website/snippets/** is in scope.
6. dbt is ALWAYS lowercase — never Dbt/DBT, even at a sentence/heading start.

Constants (Layer 1 targets) — edit website/constants.js

Rendering the specific version resolves the same-sentence collisions at the source (a core+fusion contrast now reads "dbt v1 … dbt v2" automatically). The Layer 2 prose pass trims constant-adjacent versioned forms to bare v1/v2 inline (rule 4).

Procedure

1. Read config. config/*.yml. Confirm target strings with the operator.
2. Update terminology sources FIRST so terms can't regenerate — edit the product-name tables in AGENTS.md and contributing/content-style-guide.md to the corrected mapping: retire the dbt Core and Fusion/dbt Fusion engine rows; add dbt v1 (formerly dbt Core) and dbt v2 (formerly Fusion / dbt Core 2.0), each noting dbt v1/dbt v2 at a header or sentence start and bare v1/v2 inline; keep the dbt row as generic only — use deliberately for product-agnostic statements, not as the default for former dbt Core/Fusion. Also confirm the <Constant> examples reference the specific constants.
3. Scan. python3 scripts/scan.py → inventory.json. Print the summary and HALT: counts by class, denylist hits, files needing judgment, raw-string residue.
4. Layer 1 — constants flip. Set the six values in website/constants.js (table above).
5. Layer 1b — specific-vs-generic audit + grammar fix. Partition constant_grammar_risk records by directory; spawn parallel subagents, one per file. Each:
   • fixes grammar the flip introduces (esp. fusion_engine → "dbt v2": drop the orphan article, "the dbt v2 is" → "dbt v2 is"; remove duplicate nouns);
   • audits intent: if a core/fusion constant is used generically (product-agnostic), switch that occurrence to <Constant name="dbt" />; otherwise leave the specific constant. Edit with Edit, never Write.
6. Layer 2a — mechanical prose. python3 scripts/apply_mechanical.py (auto_safe only). Deterministic. Run --dry-run first.
7. Layer 2b — judgment prose. Partition auto_safe: false by directory; spawn N≈10 parallel subagents, each with ONLY its slice + references/*.md. Apply rules 1–4 and 6. Term swaps only — see the editorial guardrail below.
8. Raw-string sweep. After edits, grep for residual old names — dbt Core, dbt Fusion, Fusion engine, Fusion — across scope INCLUDING frontmatter tags:, JSX attribute strings, hoverSnippet, and pill arrays. These are easy to miss; drive the count to 0 (excluding denylisted identifiers). Confirm pill/body agreement in _adapters-*.md (a pills array <Constant name="fusion"> must match the rewritten body).
9. Verify. python3 scripts/verify.py, then npm run build (onBrokenLinks: throw) and vale website/docs website/snippets. Never proceed on a red gate.
10. Report. Files changed, occurrences by class, structural items deferred, generic-vs-specific coin-flips, and any editorial rewrites split out (below).

Editorial guardrail — term swaps only

This is a mechanical rename, not a content rewrite. Subagents must change ONLY the product term (and the minimal surrounding grammar to keep the sentence correct). Do not add facts, rephrase for style, or introduce new sentences (e.g. "Rust engine", "adapters live in a monorepo", migration prose). Anything that changes meaning belongs in a separate content-review PR — flag it, don't apply it here.

Guardrails

• Never text-replace anything in config/never-touch.yml (CI tokens, repo slugs, AvailabilityMatrix fusion: key, component names, release-track values, compound identifiers like dbt-fusion#123).
• Never edit inside <Constant> tags (except switching a generic one to dbt), code fences, inline backticks, URLs, frontmatter id/slug, or imports.
• Structural renames (slugs, redirects, heading anchors) are a separate PR. When you must change heading text, preserve the original anchor with an explicit {#original-anchor}.
• Ship the Vale rule in references/Terminology.yml in the same PR so terms can't regress.
• Keep PR descriptions light on naming specifics until dbt Summit.

Targeted / test runs

python3 scripts/scan.py --scope-override "website/docs/docs/dbt-versions/dbt-upgrade/**/*.md"