dl-organizer/skills/vlm-library-workflow/SKILL.md

Documentation Status

• Synced with artifacts/ baseline on 2026-06-01.

---

name: vlm-library-workflow description: Operate and extend the Video Library Manager (vlm) with a safety-first, human-in-the-loop workflow across scan, parse, enrich, analyze, plan, review-plan, apply-review, execute, rollback, and developer verification. Use when requests involve organizing a video library, producing or reviewing artifacts/inventory.csv, artifacts/identities.json, artifacts/analysis.json, artifacts/plan.json, tuning VLM config templates, resolving duplicates or episode gaps, running dry-run/confirm execution, recovering changes via rollback, explaining VLM CLI usage, or developing/modifying VLM features (parser, providers, planner, executor, commands, tests).

VLM Library Workflow

Overview

Run the repository's built-in media organization pipeline with consistent safety checks and explicit output verification. Prefer incremental, reviewable steps and never skip dry-run and plan inspection before destructive operations.

Do not commit generated CSV/JSON under artifacts/ or at the repository root.

Workflow Order

Run commands in this default sequence unless the user asks for a specific stage:

1. vlm config init then set library_root in ~/.vlm/config.yaml
2. vlm scan → artifacts/inventory.csv
3. vlm parse --inventory artifacts/inventory.csv → artifacts/identities.json (v2 schema)
4. vlm enrich when bilingual titles and reputation signals are needed
5. vlm analyze --inventory artifacts/inventory.csv → artifacts/analysis.json
6. vlm plan --analysis artifacts/analysis.json → artifacts/plan.json
7. vlm review-plan → artifacts/plan_manual_review.csv (use --tui only when Textual is installed)
8. Edit CSV if needed, then vlm apply-review to sync decisions into plan.json
9. vlm execute (dry-run) and inspect summary
10. vlm execute --confirm only after explicit user confirmation
11. vlm rollback if the user requests revert

If vlm is not on PATH, prefix commands with uv run.

Preflight Checks

Run these checks before executing workflow commands:

1. Confirm current working directory is repository root.
2. Probe command availability: vlm --help or uv run vlm --help.
3. Run the target subcommand --help when options are uncertain.
4. Confirm config validity with vlm config validate after config edits.
5. Verify required input artifacts exist under artifacts/ (or paths passed via flags).
6. Treat execute --confirm as destructive and require explicit user confirmation.

Execution Rules

Follow these rules while executing tasks:

1. Prefer read-only stages first: scan, parse, enrich, analyze, plan.
2. Treat artifacts/plan.json as the reviewable contract; summarize counts and conflicts before execution.
3. Run review-plan and apply-review before execute --confirm when manual decisions are required.
4. Run dry-run (vlm execute) before vlm execute --confirm.
5. If execution is interrupted or results are incorrect, locate rollback logs and run vlm rollback.
6. Keep outputs explicit in responses: file path, record counts, and next command.
7. If the user asks for a partial workflow, run only required stages and state skipped dependencies.
8. Before execute --confirm, run vlm review-plan and report high-risk counts; pause if the user has not reviewed high-risk operations.

Decision Points

Use these decision policies:

1. Duplicate handling: choose plan.duplicate_keep (by_quality, by_reputation, by_reputation_quality_time, first_seen, manual) per user preference.
2. Enrichment: skip vlm enrich only when translations/reputation are not needed or API keys are unavailable.
3. Metadata quality: prefer vlm parse --inventory artifacts/inventory.csv when duplicate quality ranking matters.
4. Analysis-assisted planning: prefer vlm plan --analysis artifacts/analysis.json for automatic duplicate quarantine decisions.
5. Parser boundary risk: treat resolution-like tokens (1920x1080) and Sample clips as high-risk; require review-plan output before confirmation.

Output Contract

Return concise, operational summaries:

1. Commands executed.
2. Artifacts generated or updated (under artifacts/ by default).
3. Key counts (files scanned, identities parsed, duplicate groups, plan operations).
4. Risk counts from review-plan (manual_review / sample_source / high_season / high_episode / conflicts).
5. Blocking errors and exact remediation command.
6. Safe next step.

Developer Verification

When modifying VLM core logic:

1. Full suite: uv run pytest -q
2. Core components: uv run pytest tests/test_scanner.py tests/test_planner.py tests/test_executor.py
3. Property tests: uv run pytest tests/test_analysis_properties.py
4. Lint (with dev extras): uv run ruff check src tests

References

Load these references on demand:

1. references/command-recipes.md — command syntax, artifact expectations, failure triage.
2. references/workflow.md — end-to-end operator workflow.
3. references/cli-reference.md — command and config quick reference.
4. references/dev-guide.md — architecture and developer modification patterns.