vonbai/cotx-engine/cotx-enrich

When to Use

After cotx compile or cotx update reports stale enrichments, or when cotx lint shows STALE_ENRICHMENT warnings.

Workflow

Step 1: Get bounded context first

Use cotx context tools before reading source files directly.

For MCP clients:

cotx_minimal_context project_root=<project_root> task="enrich stale semantic descriptions" budget=standard
cotx_query project_root=<project_root> filter=stale layer=all

For CLI-only usage, start with:

cotx lint --json

Do not read the full repository. Use the returned modules, contracts, flows, files, and recommendations to pick a small set of enrichment targets.

Step 2: Find stale nodes

Run: cotx lint --json

This returns a JSON array of issues. Filter for type: "STALE_ENRICHMENT" entries.

Step 3: For each stale node

1. Read the node: cotx context <node_id>

• Note the layer and struct_hash
• Note what fields are stale (enriched.source_hash ≠ struct_hash)

1. Use cotx graph context first:

• For modules: inspect dependencies, depended-by modules, contracts, and flows from cotx context/query output.
• For contracts: inspect provider/consumer and interface functions.
• For flows: inspect trigger and step chain.

1. Read source only when the cotx context is insufficient: Use targeted file reads for the small file set referenced by the node.

• For modules: read the files listed in the module
• For concepts: read files in appears_in
• For contracts: read the interface functions in provider module
• For flows: read the functions in each step

1. Understand the change: Compare what the old enrichment says vs what the code actually does now

1. Write updated enrichment:

``bash cotx write <node_id> enriched.responsibility "new description based on code" cotx write <node_id> enriched.key_patterns "observed patterns" ``

Step 4: Verify

Run: cotx lint --json Confirm the stale enrichment warnings are resolved (source_hash now matches struct_hash).

Field Guide

Important

• Only enrich nodes you understand. Skip nodes where the code is unclear.
• Do NOT modify deterministic fields (files, struct_hash, etc.) — only enriched.* fields.
• Do NOT create or mutate truth graph facts from LLM output.
• Prefer cotx tool context over full-repository source reads.
• Enrichment is optional — stale enrichments don't block any operation.
• Focus on the most important nodes first (modules and contracts over individual concepts).