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.

Action	CLI Command
Create new entry	capture-cli --create --type=<type> --title="..." --description="..."
Update entry fields (tags, description)	capture-cli --update --id=<id> --tags="..." --description="..."
Change entry type (regenerates ID)	capture-cli --update --id=<id> --type=<new-type>
Add file link to entry	capture-cli --update --id=<id> --add-related-file=<path>
Search knowledge base	search-cli --query="..."
Show entry details	show-cli --id=<id>
Knowledge base overview	status-cli
Link entry to workpackage	link-cli link <id> --to=<wp-id>
Unlink from workpackage	link-cli unlink <id>
Deprecate entry	deprecate-cli <id> --reason="..."
Supersede entry	supersede-cli <old-id> <new-id>
Delete entry	delete-cli <id> --reason="..." --force
Rebuild search index	index-cli --mode=full --force
Incremental index update	index-cli --mode=incremental
File-to-entry lookup	file-index-cli --lookup=<path>
Rebuild file index	file-index-cli --rebuild

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

Type	ID Prefix	--type flag value	Use for
Technical Decision	TD-XXX	technical-decision	Architectural / tech-stack choices made by the project team
Business Rule	BR-XXX	business-rule	Mandatory invariants, prohibitions, validation requirements
Architectural Pattern	PAT-XXX	architectural-pattern	Reusable design patterns the project applies
Lesson Learned	LES-XXX	lesson-learned	Insights from past mistakes / hindsight reflections
Institutional Wiki	IW-XXX	institutional-wiki	External standards, regulations, reference docs
Stakeholder	SH-XXX	stakeholder	People / teams / orgs involved with the project
Process	PROC-XXX	process	Recurring workflows, runbooks, procedural guides

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

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

Entry Statuses

Status	Meaning	Surfaced in hooks?	Appears in index?
active	Current, valid entry	Yes	Yes
pending	Newly created, not yet validated	No	No
deprecated	Stale, no longer applicable	No	No
superseded	Replaced by another entry	No	No
archived	Retained for history	No	No

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:

Subcommand	Purpose	Example
status	Knowledge base overview (default)	/cf-knowledge status
show	Display entry details	/cf-knowledge show TD-001
link	Link entry to workpackage	/cf-knowledge link TD-001 --to=P3.2
unlink	Unlink entry from workpackage	/cf-knowledge unlink TD-001
deprecate	Deprecate an entry	/cf-knowledge deprecate TD-001 --reason="..."
supersede	Replace one entry with another	/cf-knowledge supersede TD-001 TD-005
update	Update entry metadata (or type-change with --type)	/cf-knowledge update TD-001 --tags=...
delete	Delete an entry	/cf-knowledge delete LES-003 --reason="..." --force

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", "[email protected]"). 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:

Hook Event	Script	What It Does
SessionStart	knowledge-load.sh	Loads top N entries by relevance via load-cli. Also drains pending index updates via knowledge-drain.sh
UserPromptSubmit	knowledge-search.sh	Pattern-matches prompts for search intent, runs search-cli
UserPromptSubmit	knowledge-capture.sh	Detects decision/pattern/lesson phrases, starts multi-turn capture
PreToolUse	pre-tool.sh	Looks up edited file in file-knowledge-index.json, surfaces linked entries
PostToolUse	post-tool.sh	After Write/Edit, surfaces linked entries for review
PreCompact	session-precompact.sh	Drains pending index updates via knowledge-drain.sh before context compaction
Stop	session-stop.sh	3-tier knowledge assessment: Level A (deterministic path match), Level B (change-pattern-cli evaluation), Level C (threshold-based capture prompt when >=3 files changed without A/B match). Prompts capture when modified files are knowledge-relevant

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