update-kb-article

name: update-kb-article user-invocable: true description: "update a KB article, rename a document, edit article content, update screenshots, swap screenshots, remove content, update file paths, cross-file updates, update steps in a process, combine articles, split an article, merge articles" argument-hint: "article title, filename, or description of the change needed"

Update one or more existing KB articles. This skill handles all types of article edits, from simple content changes to complex multi-file operations like merges and splits.

The user has provided: $ARGUMENTS

Core Principles

Be eager about impact. Before any change, identify every file and location that could be affected — across s/article/, s/topic/, portal/, and docs.json. Surface things the user might not have thought of.

Be conservative about execution. NEVER make a change without explicit user direction. Present findings, propose a plan, and wait for approval. When there are multiple possible changes, use the AskUserQuestion tool to let the user choose.

Never touch localized directories. Do not read, modify, suggest changes to, or reference anything in /de, /es, /fr, or /ja. These are managed separately.

Follow shared standards. When writing or rewriting any article content — including merged or split articles — read New-Article-Template.mdx for document structure and encoding conventions, and Domo-KB-Style-Guide.mdx for voice, formatting, and terminology. Read both files before writing any content.

Step 1: Identify the article(s) and change type

If $ARGUMENTS names a file or topic, confirm the exact file path before proceeding.

To find an article by title keyword:

grep -rl "title:.*keyword" s/article/ s/topic/

To find by filename:

ls s/article/ | grep keyword

Once the file(s) are identified, ask the user what type of change they need — or confirm it if already stated. The change types are:

1. Rename — change the article title, filename, or both
2. Content update — edit body text, callouts, or other prose
3. Image/screenshot swap — replace one or more images
4. Content removal — delete a section, step, or block
5. File path update — rename a file and update all references to it
6. Cross-file change — the same change needs to appear in multiple articles
7. Step/process update — add, remove, or reorder steps in a numbered list
8. Navigation move — relocate the article in the site nav
9. Merge — combine two or more articles into one
10. Split — break one article into two or more

Use AskUserQuestion if you need to clarify which type applies, or if the user's description could map to more than one type.

Step 2: Impact analysis

Run impact analysis before proposing any changes. The scope depends on the change type.

For any change involving a filename or article path

Search for all references to the file across the codebase:

# Root-relative links: /s/article/Article-Name
grep -rn "s/article/Article-Name" s/article/ s/topic/ portal/ docs.json

# Absolute links: https://domo-support.domo.com/s/article/Article-Name
grep -rn "domo-support.domo.com/s/article/Article-Name" s/article/ s/topic/ portal/

Both link formats must be found and updated. Do not assume only one form is in use.

Also check docs.json for the page entry:

grep -n "Article-Name" docs.json

For content updates and cross-file changes

If the change involves a feature, behavior, or setting that may be documented in multiple articles, search for the feature name across all articles to surface related files the user may not have considered:

grep -rl "feature name" s/article/ s/topic/

Present the list to the user and ask: which of these files also need to reflect this change?

For image/screenshot swaps

Identify the current image filename(s) in the article and check if the same image is referenced in any other article:

grep -rn "image-filename.png" s/article/ s/topic/ portal/

If the image is shared, warn the user before any changes.

For merges

For each source article being merged:

1. Find its current location in docs.json
2. Find all inbound links to it from other articles (both link formats)
3. Note its title and frontmatter

For splits

1. Find all inbound links to the original article from other articles
2. Identify which inbound links should point to which new article after the split
3. Note the original's location in docs.json

Step 3: Present findings and confirm the plan

After impact analysis, present a structured summary:

• Files to be modified: list each file and what would change
• Files to be created: (merges, splits)
• Files to be deleted: (merges, splits, after user confirms)
• docs.json changes: any navigation entries to add, remove, or move
• Link updates: list of files with inbound links that need updating
• Things to watch out for: anything ambiguous, risky, or that requires a human judgment call (e.g., which inbound links should point to which new article after a split)

If the list is long or involves choices, use AskUserQuestion to walk the user through their options rather than dumping everything at once.

Do not proceed until the user has explicitly approved the plan.

Step 4: Execute approved changes

Make changes only for what the user has explicitly approved. Work through the change list one item at a time.

Renaming a title only (frontmatter, not filename)

Edit the title: field in the article's frontmatter. The filename and all links remain unchanged.

Renaming a file

1. Create the new file (copy content, update the title: if it's also changing).
2. Delete the old file.
3. Update every inbound link — both root-relative and absolute forms.
4. Update the docs.json page entry.

Content updates, removals, step changes

Use the Edit tool with enough surrounding context (2–3 lines) to make old_string unique. Never rewrite more than what was approved.

Image/screenshot swap

Update the src attribute in the <Frame> or <img> tag. Update alt text if appropriate. Do not move or delete image files — note to the user that the image asset itself must be updated separately in images/kb/.

Navigation move

Invoke the add-to-nav skill. Do not attempt to edit docs.json directly for navigation moves.

Merge

1. Draft the merged article content and show it to the user for approval before writing any files.
2. Write the new merged file to s/article/.
3. Add it to docs.json navigation (use add-to-nav skill).
4. Update all inbound links from other articles to point to the new file.
5. Ask the user explicitly whether to delete each source article before deleting anything.
6. If deleting, remove from docs.json as well.

Split

1. Draft both (or all) new article files and show them to the user for approval before writing any files.
2. Write the new files to s/article/.
3. Add each to docs.json navigation (use add-to-nav skill).
4. For each inbound link to the original article, determine (with the user) which new article it should point to, then update.
5. Ask the user explicitly whether to delete the original article before deleting anything.
6. If deleting, remove from docs.json as well.

Step 5: Verify

After all edits:

1. Validate docs.json if it was changed:

   python3 -c "import json; json.load(open('docs.json')); print('docs.json is valid JSON')"
   

2. Confirm no broken references remain for any renamed or deleted file:

   grep -rn "old-filename" s/article/ s/topic/ portal/ docs.json
   

Report any remaining references to the user.

Step 6: Output

Tell the user:

• What was changed, created, or deleted
• Any follow-up actions they need to handle manually (e.g., uploading new image assets, updating absolute links on the live Salesforce support site)
• Any files that were intentionally left unchanged and why