/trace-file-lineage

name: trace-file-lineage
description: Trace the origin, ancestry, downstream impact, searchable text, and task/run history of files and artifacts in local workspaces. Use for questions about which code, notebook, data, editable document, configuration, command, or agent task produced an image, PDF, dataset, model, report, or other file; for stale-output and orphan investigations; for high-volume agent-run summaries; for W3C PROV, DVC, OpenLineage, or local code-graph interoperability; and for prospective file-producing task capture. Supports broad native text, Python/notebook and conservative JavaScript/TypeScript lineage, structured documents, optional local OCR, Git evidence, focused visualizations, and Obsidian export. Works with Codex, Claude Code, and other Agent Skills-compatible hosts without vendor APIs. Do not use as a file organizer or as proof of historical causality without captured evidence.

Trace File Lineage

Keep all analysis local and non-destructive. Never execute scanned project code, follow external symlinks, expose secret contents, or move source files.

Choose a workflow

Use retrospective forensics when the artifact predates capture. Infer candidates, cite evidence, retain alternatives, and state uncertainty.

Use prospective capture before a future file-producing command or agent task. A manual or hook boundary proves only observed co-change. The `run` wrapper may verify that its child command changed an artifact version; it still does not name an internal writer function.

Set `LINEAGE` to `<skill-dir>/scripts/lineage.py` in the POSIX examples below. An installed package instead provides the `lineage` command (and the equivalent `python -m lineage_core`), which is preferable when available; in PowerShell use `py -3 $Lineage ...`. Do not assume Bash or a POSIX separator. Build filesystem paths with `pathlib`, pass child arguments as arrays, and never request shell interpolation.

Query commands default to Markdown and accept `--format json` when you need to parse the result. `doctor` also defaults to a readable report; use `doctor --format json` for the complete machine-readable capability ledger.

Two modes

Manual: answer a question about an existing project. Most answers about files created before any capture existed are `candidate`, not `verified`; say so.

Continuous: the user ran `lineage enable`, which wrote a required instruction into this project's `CLAUDE.md` and `AGENTS.md`. When that block is present you must record a boundary at the end of every task that changed files, and you must place new files according to the existing layout. Check with `lineage status`.

Before creating files in an unfamiliar project, read the conventions first:

python3 "$LINEAGE" layout --root .

Put outputs where comparable outputs already live. Reuse existing directories rather than inventing `output_final_v2/`, `results_new/`, or a directory named after today's date. Keep names short; when an output supersedes an earlier one, reuse the same path so the history is a version chain rather than near-duplicates.

To show the user a graph, let them choose the angle rather than always rendering the same diagram:

python3 "$LINEAGE" views --list
python3 "$LINEAGE" views --view source-chain --file report.pdf --root . --format mermaid

Retrospective forensics

For the usual “where did this artifact come from?” question, use the single first-run command. It incrementally refreshes the index before explaining:

python3 "$LINEAGE" explain path/to/artifact --root . --format markdown

Use `--no-scan` only when the index is already current. Build or refresh the local index separately for batch investigation:

python3 "$LINEAGE" scan --root .

Use `scan --full` when content may have changed without a reliable size/mtime change; it forces hashing and extraction instead of reusing metadata.

Find by fuzzy filename or indexed text, then narrow the explanation:

python3 "$LINEAGE" find "final panel" --root . --type image --thumbnails
python3 "$LINEAGE" search "needle" --root . --source native
python3 "$LINEAGE" search "needle" --root . --source ocr

Answer the narrowest user question first:

python3 "$LINEAGE" why path/to/artifact --root . --format markdown
python3 "$LINEAGE" alternatives path/to/artifact --root . --format markdown
python3 "$LINEAGE" impact path/to/input --root . --format markdown
python3 "$LINEAGE" path source.file target.file --root . --format markdown
python3 "$LINEAGE" stale path/to/input --root . --format markdown
python3 "$LINEAGE" orphans --root . --format markdown

Report the conclusion first, then the top-ranked chain, plain-language assurance, factual evidence, credible alternatives, rejection reasons, and missing evidence. Say “insufficient evidence” instead of choosing arbitrarily.

Read [references/confidence.md](references/confidence.md) before adjudicating ambiguous or high-stakes lineage. Read [references/adapters.md](references/adapters.md) when explaining parser coverage or degraded behavior. Read [references/schema.md](references/schema.md) when consuming JSON or SQLite.

Prospective capture

Prefer the command wrapper for a safe, non-interactive local command:

python3 "$LINEAGE" run --root . --task "Render figures" -- python3 scripts/render.py

On normal completion, `run` prints a concise changed-file receipt to standard error without altering the child's standard output. Use `--no-receipt` to suppress it, or `receipt --root .` for the latest finalized complete manifest.

For an agent task or a command that should not be wrapped, use boundaries:

python3 "$LINEAGE" snapshot --root . --output .file-lineage/before.json
# Perform the task.
python3 "$LINEAGE" record --root . --before .file-lineage/before.json --task "Prepare submission"

Plugin hooks use documented `UserPromptSubmit` and `Stop` events as a best-effort turn boundary in Codex and Claude Code. P