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

Documentation Status

• Synced with refactor baseline on 2026-02-16.

---

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, execute, rollback, and developer verification. Use when requests involve organizing a video library, producing or reviewing inventory.csv/identities.json/analysis.json/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.

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 to produce inventory.csv
3. vlm parse --inventory inventory.csv to produce metadata-rich identities.json
4. vlm enrich when bilingual titles and reputation signals are needed
5. vlm analyze --inventory inventory.csv to produce analysis.json
6. vlm plan --analysis analysis.json to produce plan.json
7. vlm execute (dry-run) and inspect summary
8. vlm execute --confirm only after explicit user confirmation
9. vlm rollback if the user requests revert

Preflight Checks

Run these checks before executing workflow commands:

1. Confirm current working directory is repository root.
2. Probe command availability in this order:
   1. vlm --help
   2. if unavailable, switch all commands to 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 files exist before downstream stages.
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 plan.json as reviewable contract; summarize counts and conflicts before execution.
3. Run dry-run (vlm execute) before vlm execute --confirm.
4. If execution is interrupted or results are incorrect, locate rollback logs and run vlm rollback.
5. Keep outputs explicit in responses: file path, record counts, and next command.
6. If user asks for partial workflow, run only required stages and clearly state skipped dependencies.
7. Before execute --confirm, run vlm review-plan --input plan.json --output plan_manual_review.csv and report high-risk counts.
8. If high-risk operations > 0, default to pause and require user explicit override to continue confirm execution.

Decision Points

Use these decision policies:

1. Duplicate handling: Choose plan.duplicate_keep policy (by_quality, by_reputation, first_seen, manual) based on user preference.
2. Enrichment: Skip vlm enrich only when user does not need translations/reputation or API keys are unavailable.
3. Metadata quality: Prefer vlm parse --inventory inventory.csv when duplicate quality ranking matters.
4. Analysis-assisted planning: Prefer vlm plan --analysis analysis.json when user wants automatic duplicate quarantine decisions.
5. Parser boundary risk: Treat filenames containing resolution-like 1920x1080/1440x1080 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.
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, verify integrity with these recipes:

1. Full Suite: pytest
2. Core Components: pytest tests/test_scanner.py tests/test_planner.py tests/test_executor.py
3. Property Tests: pytest tests/test_analysis_properties.py
4. Integration: pytest tests/test_reports_integration.py

References

Load these references on demand:

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