usm/cli-enrich

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

Usage

# Enrich all .usm files with TODO placeholders
usm enrich

# Enrich a single file
usm enrich --file .usm/features/auth/login.usm

# Show what would change without calling LLM or writing
usm enrich --dry-run

# Override the LLM model
usm enrich --model anthropic/claude-sonnet-4-5

Why this exists

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.

How it works

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

Guarantees

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

Test specifications

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