Add product knowledge

Add Product Knowledge

Add a new entry to the product knowledge base used by the product-expert agent.

Purpose

Use this skill to capture product context mid-conversation — after a requirements session, after debugging a complex domain flow, or when you learn something about the product that should be preserved for future sessions.

The product-expert agent reads all .md files in the configured product-knowledge directory. This skill creates a properly-structured file and updates the manifest so the new entry is immediately searchable.

Arguments

/add-product-knowledge                  # Full wizard
/add-product-knowledge Payment Flow     # Pre-fill title, wizard for rest

Context

Arguments: $ARGUMENTS

---

Configuration

if [ -f "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh" ]; then
  source "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh"
elif [ -f "$HOME/.claude/shared/resolve-config.sh" ]; then
  source "$HOME/.claude/shared/resolve-config.sh"
else
  echo "ERROR: resolve-config.sh not found — reinstall the nexus plugin: /plugin install nexus@claude-skills" >&2
  exit 1
fi

IFS='|' read -r KB_PATH _TYPE <<< "$(resolve_artifact_typed product-knowledge .)"
if [[ ! -d "$KB_PATH" ]]; then
  echo "ERROR: Knowledge base directory not found: $KB_PATH" >&2
  exit 1
fi

If the location type is git, sync before writing:

if [[ "$_TYPE" == "git" ]]; then
  git -C "$KB_PATH" pull --ff-only 2>/dev/null || true
fi

---

Workflow

Step 1: Resolve title

Parse $ARGUMENTS. If non-empty, treat the full string as the initial title suggestion.

If $ARGUMENTS is empty, use AskUserQuestion:

What do you want to document?
(e.g. "Payment Flow Architecture", "Auth Token Lifecycle", "Subscription Tier Rules")

Store as {title}.

Step 2: Choose category

List existing categories (subdirectories of $KB_PATH):

find "$KB_PATH" -mindepth 1 -maxdepth 1 -type d -not -name '.*' \
  | xargs -I{} basename {} | sort

Use AskUserQuestion with the list as options plus "other":

Category for "{title}":
1. architecture
2. api
3. business-rules
4. data-models
... (existing categories)
N. other (enter a new category name)

Store as {category}. If "other", ask for the new category name.

Step 3: Gather content

Use AskUserQuestion:

What should this entry document?

You can:
- Describe it in plain text (I'll structure it)
- Paste existing notes or diagrams
- Say "from conversation" to extract from our current discussion

Store as {raw_content}.

If the user says "from conversation", extract the most relevant product/domain insight from the current conversation context — focus on business rules, architecture patterns, API contracts, data models, or workflow states. Exclude code-level details (those belong to archaeologist).

Step 4: Structure the content

Based on {category}, produce structured markdown using the appropriate template:

architecture — system components, integration patterns, service boundaries, data flow api — endpoints, request/response shapes, auth requirements, rate limits business-rules — domain logic, validation rules, workflow states, edge cases data-models — entity definitions, field constraints, relationships, lifecycle other — freeform with headings derived from the content

Keep it factual and cite evidence where possible. No speculation. If something is uncertain, mark it *(unverified)*.

Step 5: Derive filename

# Slugify the title
SLUG=$(echo "{title}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-\|-$//g')
DEST="$KB_PATH/{category}/${SLUG}.md"

Check if the file already exists:

if [[ -f "$DEST" ]]; then
  # Show the user what's there and ask: overwrite, rename, or cancel
fi

Step 6: Write the file

Write $DEST with this structure:

---
tags: [{derived tags}]
---

# {title}

{structured content}

Tags are inferred from the title and content — use 3–6 short lowercase terms.

Create the category directory if it doesn't exist:

mkdir -p "$KB_PATH/{category}"

Step 7: Rebuild manifest

Invalidate the manifest so product-expert picks up the new file immediately:

MANIFEST="$KB_PATH/manifest.json"
if [[ -f "$MANIFEST" ]]; then
  # Touch last_updated to force product-expert to rebuild on next read
  _TMP=$(mktemp) && jq '.last_updated = "1970-01-01T00:00:00Z"' "$MANIFEST" > "$_TMP" \
    && mv "$_TMP" "$MANIFEST"
fi

Step 8: Commit (git locations only)

If $_TYPE == "git", follow the sanctioned KB-write pattern in full: ${CLAUDE_PLUGIN_ROOT}/shared/kb-write-pattern.md. Both git commit (Call 2) and git push (Call 3) must lead their own Bash tool calls so the guard engages — for the push that means resolving the branch inline in the push argument, on one line, since shell variables do not survive across Bash tool calls. Prefix the push with NEXUS_KB_WRITE=1 SECURITY_AUDITOR_BYPASS=1 (both logged to stderr — that WARN is the tripwire); do not call record-audit.sh:

# Call 1 — stage.
cd "$KB_PATH"
git add "$DEST" "$MANIFEST"

# Call 2 — commit leads the call (credential scan).
git commit -m "docs(product-knowledge): add {title}"

# Call 3 — push must lead, on ONE line, so the guard engages and logs the bypass WARNs.
NEXUS_KB_WRITE=1 SECURITY_AUDITOR_BYPASS=1 git push origin -- "$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##' | grep . || timeout 10 git ls-remote --symref origin HEAD 2>/dev/null | awk '/^ref:/{sub("refs/heads/","",$2);print $2;exit}' | grep . || echo master)"

Step 9: Confirm

✓ Knowledge base entry created

  File:     {category}/{slug}.md
  Title:    {title}
  Tags:     {tags}
  Location: $DEST

The product-expert agent will pick this up on the next invocation.
Run /rebuild-index product-knowledge to rebuild the full manifest now.