Kb Article Writing

The skill is about how to write the article, not how to guess the facts.

Before drafting, ground the article in current product reality.

Gather Facts First

Before writing or rewriting a KB article, identify the source of truth for the content itself.

Use this order:

1. Existing KB and nearby KB articles
   • check whether the topic already exists in published or draft form
   • reuse exact product terminology and neighboring workflow boundaries when they are still correct
2. Source code and product implementation
   • when the article is about current product behavior, treat source as the main factual anchor
   • inspect the relevant repo and UI/API code paths before asserting how the product works
3. App-specific settings paths, labels, and screenshots
   • verify exact UI labels, menu names, and flows from code or current product-facing references
4. Support/reference notes only as secondary context
   • use the style guide and review notes for voice and structure
   • do not use them as the factual source for current functionality when code is available

If the article depends on behavior that may have changed recently, verify before drafting. Do not write KB copy from memory alone.

Map Topic To Evidence

Use the topic to decide where the facts should come from:

• frontend/editor/recording/publish UI:
  • inspect ../alitu-frontend
• backend behavior, hosting, account state, publishing integrations, workflow state:
  • inspect ../alitu-commander
• processing/export/media-generation behavior:
  • inspect ../alitu-processor
• local multi-service boot/wiring questions:
  • inspect ../../ (alitu-local root)

When the article spans multiple systems, read only enough from each repo to confirm the behavior the article claims.

Content Before Style

Separate these two jobs:

• content truth
  • what the product actually does
  • what the limits, prerequisites, or edge cases are
  • what labels and settings are called
• style shaping
  • how to present that truth in Alitu KB house style

Do not let style confidence hide factual uncertainty.

If the implementation is unclear, stale, or contradictory:

• say so
• resolve it from source before drafting
• or write the article as a scoped draft with explicit uncertainty for the human reviewer

Assets (Images and Videos)

Articles may include images (screenshots, GIFs) or videos. How these are handled depends on whether they already exist.

Existing articles

Images and videos in existing articles are already hosted on Intercom's CDN (downloads.intercomcdn.com). Keep these URLs as-is — do not re-upload or change them unless the asset itself needs replacing.

New or replacement assets

The Intercom API does not support file uploads. New images and videos are hosted on S3 instead.

Workflow:

1. Create assets (screenshots/GIFs) using the kb-gif-capture skill or manually.
2. Place all finished assets for the article in /private/tmp/<article-slug>-assets/.
3. Upload to S3 using the upload script:

   src/alitu-knowledge-base/skills/kb-gif-capture/scripts/upload_assets.sh /private/tmp/<article-slug>-assets <article-slug>
   

4. The script prints the public URL for each uploaded file. Use these URLs in the article HTML.

URL pattern: