usm/cli-enrich

The usm enrich command fills in TODO: describe placeholders in .usm files using an LLM (LiteLLM, OpenAI, Anthropic, or Ollama).

Intent

Scanned .usm files contain TODO placeholders for summary, intent, decisions, flows, contracts, and tests. Enrich calls an LLM with source code context to fill these in, preserving existing human-written content.

Flows

Enrich a single .usm file (enrich-single-file)

User enriches one file with LLM-generated content

1. parse → .usm file with TODO placeholders
2. setup → source code context from referenced file paths
3. post → LLM API with system prompt + user prompt
4. parse → LLM response YAML
5. merge → filled fields into original .usm, preserving human edits

Contracts

enrich-preserves-human-edits

Enrich must never overwrite fields that already have non-TODO content

Acceptance criteria:

• [ ] Fields with TODO: describe are filled
• [ ] Fields with existing content are preserved
• [ ] preserve_human_edits defaults to true

Tests

enrich-fills-todos

Given:

• usm_with_todo_fields: true

Then:

• assertion: TODO fields replaced with LLM content
• assertion: non-TODO fields unchanged

enrich-dry-run

Given:

• dry_run: true

Then:

• assertion: no files written
• assertion: planned changes reported

Implementation

• Primary: src/enrich/index.ts
• Test code status: none

See Also

• usm/cli-scan