Knowledge Management

CLI Usage: When unsure about a CLI's interface or flags, run it with --help first. Do NOT attempt to discover functionality by reading plugin source code — doing so leads to incorrect execution from assumptions made without context of the holistic flow.

Knowledge Management Skill

Purpose

This skill provides guidance for Claude on managing persistent project knowledge in the CLEAR framework. It covers capturing decisions, searching the knowledge base, viewing entries, managing lifecycle (linking, deprecation, supersession, update, deletion), and understanding automatic knowledge hooks.

Plugin Root Resolution

CLI commands in this skill reference $CLEAR_PLUGIN_ROOT — a .claude/settings.json env var the shell expands. The SessionStart hook persists it, but settings env vars load at session launch, so on a brand-new consumer's first session (before its next restart) the variable is empty and node "$CLEAR_PLUGIN_ROOT/build/..." fails with MODULE_NOT_FOUND.

First-session bootstrap — if $CLEAR_PLUGIN_ROOT is empty, set it inline in the same Bash call as the CLI (each Bash call is a fresh shell, so a separate export would not carry over):

export CLEAR_PLUGIN_ROOT="${CLEAR_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"

Prepend it to the CLI in one shell line: export CLEAR_PLUGIN_ROOT="${CLEAR_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"; <node "$CLEAR_PLUGIN_ROOT/build/..." command>. ${CLAUDE_PLUGIN_ROOT} resolves in this SKILL.md body to the actually-loaded plugin path; once the consumer restarts, $CLEAR_PLUGIN_ROOT is populated and the assignment is a harmless no-op. Reference files are left unchanged.

Command Reference

All CLIs at $CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/. Run with --clear-dir=./.clear.

Key distinction: link-cli manages workpackage associations only. To add file links (related_files), use capture-cli --update --add-related-file.

When to Take Action vs. Just Answer

TAKE ACTION (run CLIs) when user says:

• "capture this decision" / "save this as a technical decision" → /cf-knowledge create or capture-cli --create
• "search knowledge for X" / "find what we decided about X" → search-cli --query=X
• "show me TD-001" → /cf-knowledge TD-001 or /cf-knowledge show TD-001
• "create a business rule for X" → capture-cli --create --type=business-rule
• "rebuild the knowledge index" → index-cli --mode=full --force
• "link TD-001 to WP-P3.2" → /cf-knowledge link TD-001 --to=P3.2
• "deprecate LES-003" → /cf-knowledge deprecate LES-003 --reason="..."
• "update TD-001 tags" → /cf-knowledge update TD-001 --tags=new-tag1,new-tag2
• "delete LES-003" → /cf-knowledge delete LES-003 --reason="..." --force
• "knowledge status" → /cf-knowledge status

JUST READ FILES (no CLIs) when user asks:

• "what decisions have we made?" → Read entries in .clear/knowledge/entries/
• "list all patterns" → Grep for type: architectural-pattern in .clear/knowledge/entries/
• "do we have any knowledge about X?" → Grep .clear/knowledge/entries/ for keywords

Do NOT use Write or Edit on .clear/ files. All mutations go through CLIs, which use fs.writeFileSync (invisible to the PreToolUse guard).

Knowledge Types

All entries are stored in .clear/knowledge/entries/ (flat directory, no subdirectories).

The SQLite search index is at .clear/knowledge/index.db.

Entry Statuses

New entries created via capture-cli --create start as active. Use pending status when an entry needs review before surfacing (e.g., auto-extracted entries). Pending and deprecated entries are excluded from the file-knowledge-index and load-cli output.

Unified Entry Point: /cf-knowledge

The /cf-knowledge command routes to all knowledge subcommands via router.ts:

node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/router.js" \
  <subcommand> [args] --clear-dir=./.clear

Available subcommands:

Direct ID shorthand: /cf-knowledge TD-001 is equivalent to /cf-knowledge show TD-001.

CLI Reference

All CLIs are at $CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/. Always run with --help first if unsure about flags.

capture-cli — Create and Update Knowledge Entries

# Create a new entry
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/capture-cli.js" \
  --clear-dir=./.clear \
  --create \
  --title="<Decision Title>" \
  --type=technical-decision \
  --tags="tag1,tag2,tag3" \
  --description="<Brief description>" \
  --session=<session-number>

# Update an existing entry
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/capture-cli.js" \
  --clear-dir=./.clear \
  --update \
  --id=<entry-id> \
  --tags="new-tag1,new-tag2" \
  --description="Updated description" \
  --add-related-file="src/auth/middleware.js" \
  --session=<session-number> \
  --workpackage=<workpackage-id>

Create modes: --detect (scan text for capture triggers), --confirm (process user confirmation), --create (direct creation), --check-state (check pending capture).

Create flags: --title, --type, --tags, --description, --session, --supersedes=<id> (mark as superseding another), --workpackage=<id> (auto-link to workpackage after creation).

Institutional-wiki (--type=institutional-wiki) flags: --source=<string> (canonical external citation, e.g., "ISO 27001:2022"), --source-updated=<date> (when the source was last revised), --scope=<string> (one-line statement of what this entry covers). Stored as frontmatter and surfaced in the body template's Source/Scope/Content sections. Silently ignored on non-IW types.

Process (--type=process) flags: --trigger-event=<string> (the event that initiates the process, e.g., "session-start", "deploy-trigger"), --frequency=<string> (execution cadence, e.g., "weekly", "on-demand", "every release"), --tools=<string> (tools/commands used, e.g., "just, jq, gh"), --automation-hook=<string> (reference to an automation entrypoint, e.g., a script path). Stored as frontmatter and surfaced in the body template's Trigger / Prerequisites / Steps / Verification sections. Silently ignored on non-PROC types. A fifth PROC frontmatter field — promotion_status — is reserved for the process-to-skill promotion lifecycle; no CLI flag is plumbed at create time, and the field stays null until promotion runs.

Stakeholder (--type=stakeholder) flags: --entity-type=<string> (REQUIRED at CLI boundary; e.g., "team", "individual", "org", "role" — createEntry rejects SH creation with a status:error envelope when omitted, mirroring the title+type cross-context gate), --role=<string> (e.g., "Platform Lead", "On-call rotation"), --owns=<path,path,...> (comma-separated relative paths the stakeholder owns; trim + filter empty; absolute paths and .. traversal rejected — same rule as --add-related-file=), --contact=<string> (e.g., "#payments-oncall", "team@example.com"). Stored as frontmatter and surfaced in the body template's Entity / Role / Owns / Contact sections. Triggers lazy buildOwnerIndex() after the first SH entry create — .clear/state/owner-index.json maps owns paths to SH entry IDs and is consulted by PreToolUse alongside the file-knowledge-index. Silently ignored on non-SH types.

Audit + observability flags: --via=<mode> declares the capture origin (modes: direct_create | pattern_detected | extraction | bulk; default direct_create applied at audit-emit time). --matched-pattern=<description> echoes the CapturePatternDef.description string when the entry was triggered by a YAML capture pattern (used by daemon/curation tools to attribute fires to specific patterns). --session-id=<guid> and --session-number=<n> together enable canonical audit-log emission to .clear/audit/session_N.jsonl for create operations — the production hook chain (scripts/knowledge/knowledge-capture.sh) reads these from .clear/state/session.json automatically; direct CLI users supply them explicitly. If either is absent, audit emit is silently skipped (legacy --session=<n>-only path preserved). Decline / failure / state-expired events are written to .clear/state/capture-pattern-log.jsonl regardless of session flags — that surface is daemon-curated, not single-event audit.

Update flags: --id=<id> (required), --tags=<comma-separated>, --description=<text>, --add-related-file=<path> (repeatable), --session=<number>.

Type-change (--update --id=<id> --type=<new-type>): Pass --type= in update mode to reclassify an entry under a new type with regenerated ID. The old entry is preserved on disk with status: superseded and superseded_by: NEW-NNN; a new entry is created at NEW-NNN.md with the body copied verbatim and supersedes: OLD-NNN. All third-party entries that referenced the old ID via supersedes or superseded_by are cascaded to the new ID — the cascade is mandatory. Type-change emits a 'supersede' audit row (from the unified supersession primitive) plus a 'update' audit row with metadata.operation: 'type-change' so queries can filter type-changes specifically. Type-change to stakeholder requires --entity-type=... at the CLI boundary (mirrors the create-time SH gate). Type-change is rejected on entries already superseded or deprecated, or when the new type matches the current type. The return JSON has oldId, newId, action: 'type-change', and cascadedRefs at the top level.

Output is JSON. Parse to confirm success and extract the entry ID and file path.

Tagging Guidelines

Tags are the primary search signal (P1 exact match). Poor tagging forces multiple search passes. Follow these rules for every capture and update operation.

MANDATORY: Every entry MUST have at least one domain tag and one specific tag.

Tag Tiers

1. Domain tags (REQUIRED — at least 1) Broadest category the entry belongs to. Enables "show me everything about X" queries. Examples: database, ipc, ui, packaging, testing, auth, config, build

2. Specific tags (REQUIRED — at least 1) Precise technology, library, or concept. Enables targeted lookup. Examples: better-sqlite3, electron-rebuild, wal, vite, nsis

3. Architectural tags (when applicable) Cross-cutting concerns. Enables "show me all performance decisions" queries. Examples: architecture, performance, error-handling, security, scalability

4. Project-scoped tags (when applicable) Project components or structure. Enables "show me all task-service knowledge." Examples: task-service, settings-service, poll-engine, phase-1

5. Lifecycle tags (when applicable) Nature of the decision. Enables "what did we defer?" queries. Examples: deferred, workaround, constraint, migration, deprecated

Rules

• Minimum 2 tags per entry (1 domain + 1 specific)
• Use lowercase, hyphenated format (e.g., error-handling, not Error Handling)
• Prefer existing tags over inventing new ones — check /cf-knowledge status for established tags before creating synonyms
• When unsure about domain tag, ask: "If someone searched for everything about this topic, what single word would they use?"

Edge-case exception: If a genuine outlier makes 2-tag compliance impossible (e.g., highly cross-cutting or generalised entry), use the closest available tags and note the exception in the entry description. Do NOT stall on tagging — proceed with the best available pairing rather than ask the user mid-capture, unless the entry's domain is so ambiguous that no defensible tags exist.

delete-cli — Delete a Knowledge Entry

node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/delete-cli.js" \
  <entry-id> --reason="<reason>" --clear-dir=./.clear

Flags:

• --reason=<text> — Reason for deletion (required)
• --force — Skip confirmation for active entries
• --clear-dir=<path> — Path to .clear directory (required)

Shows impact analysis (linked WPs, supersession chains, related entries) before deletion. Without --force, active entries require explicit confirmation.

search-cli — Search Knowledge Base

# Search by query
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/search-cli.js" \
  --clear-dir=./.clear \
  --query="authentication approach"

# Detect search intent in user text
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/search-cli.js" \
  --clear-dir=./.clear \
  --detect-only --text="what did we decide about caching"

Uses 3-pass search: P1 (tag exact match), P2 (title keyword), P3 (TF-IDF cosine similarity). Flags: --max-results=<n>, --include-superseded.

show-cli — Display Entry Details

node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/show-cli.js" \
  --clear-dir=./.clear --id=TD-001

load-cli — Load Knowledge at Session Start

node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/load-cli.js" \
  --clear-dir=./.clear \
  --level=balanced \
  --context="auth,security" \
  --workpackage=P3.2

Levels: minimal, balanced, comprehensive. Ranks entries by relevance score (active status, tag matches, recency, type).

index-cli — Rebuild Knowledge Index

# Full rebuild
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/index-cli.js" \
  --clear-dir=./.clear --mode=full --force

# Incremental update
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/index-cli.js" \
  --clear-dir=./.clear --mode=incremental

Rebuilds the SQLite search index (.clear/knowledge/index.db). The index is automatically rebuilt inline after every --create and --update operation. Manual rebuild is only needed after direct file edits or if search results seem stale.

link-cli — Link Entry to Workpackage

# Link
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/link-cli.js" \
  link TD-001 --to=P3.2 --clear-dir=./.clear

# Unlink
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/link-cli.js" \
  unlink TD-001 --clear-dir=./.clear

deprecate-cli — Deprecate an Entry

node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/deprecate-cli.js" \
  TD-001 --reason="Superseded by new approach" --clear-dir=./.clear

Shows impact analysis (linked WPs, supersession chains) before proceeding. Use --force to skip confirmation.

supersede-cli — Replace One Entry with Another

node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/supersede-cli.js" \
  TD-001 TD-005 --clear-dir=./.clear

Marks old entry as superseded, links both entries. Use --force to skip chain depth validation.

status-cli — Knowledge Base Overview

node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/status-cli.js" \
  --clear-dir=./.clear

Shows entry counts by status/type, recent activity, index health, and supersession chains.

file-index-cli — File-to-Knowledge Index

# Rebuild reverse index
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/file-index-cli.js" \
  --rebuild --clear-dir=./.clear

# Look up entries linked to a file
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/file-index-cli.js" \
  --lookup=src/auth/middleware.js --clear-dir=./.clear

# Update index for a specific entry
node "$CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/file-index-cli.js" \
  --update=TD-001 --clear-dir=./.clear

Automatic Knowledge Hooks

These run without user action:

Internal helpers (not user-facing):

• knowledge-drain.sh — Shared function that drains pending index updates (marker-file fallback recovery). Called by knowledge-load.sh at session start and session-precompact.sh at PreCompact.
• change-pattern-cli — Evaluates changed files against knowledge patterns for Level B assessment in the Stop hook.

Token Efficiency

Decision framework for load-level selection:

• Session start with no specific WP context → load-cli --level=minimal (top-N relevance-ranked summaries only)
• Active WP work or focused investigation → load-cli --level=balanced (default — summaries + recent activity)
• Deep cross-cutting investigation or audit work → load-cli --level=comprehensive (full bodies for top entries)
• Quote a single entry's full body → show-cli --id=<id> (do not re-load the whole base)

Budget allocation reference:

• Per-entry summary (hook surfacing / load-cli minimal): ~0.5% of context
• Per full entry (show-cli or load-cli comprehensive): ~2-5%
• Target total knowledge load: <10% of session budget — if approaching this, prefer minimal + targeted show-cli over comprehensive load