Artifact Management

Artifact Management

Use this skill when analysis outputs should persist beyond the current conversation.

When to store artifacts

Store analysis artifacts when:

• the user asks to save, export, share, cite, or reproduce an analysis

• a chart, report asset, or presentation-ready output is generated

• the analysis may be reused for a decision, review, dashboard follow-up, or external-facing answer

• the query result is non-trivial and the SQL, assumptions, or caveats matter for interpretation

Do not write files into a repository or long-lived location unless the user requested persistence or approved the destination.

What to store

Prefer storing enough context for someone to reproduce and critique the analysis later:

• original user question or decision context

• metric definitions, assumptions, population, grain, time window, filters, and exclusions

• source models/tables and relevant data-dictionary references

• final SQL or query source

• result snapshot, such as CSV, JSON, Parquet, or a small markdown table

• narrative summary, findings, evidence, confidence, and caveats

• generated plot files and the underlying data used to create them

• reproduction instructions, including commands or tool steps when helpful

• creation timestamp and author/tool context when useful

Recommended local structure

Use a dated, human-readable slug for each analysis package:

analyses/
└── 2026-05-27-active-users-trend/
    ├── README.md
    ├── query.sql
    ├── result.csv
    ├── summary.md
    ├── chart.html
    ├── chart.png
    └── metadata.json

For lightweight exports, a single CSV or markdown file is fine. For reusable or report-ready work, prefer the package structure above.

Reproducible generated artifacts

When an artifact is generated by code, preserve enough context to reproduce and safely modify it later:

• Save the generator script or notebook alongside the generated outputs when practical.

• Keep generated files reproducible from the saved script and source data.

• If fixing a generated artifact, update the generator and regenerate the output. Avoid only hand-patching generated files, because that causes drift between the source script and artifact.

• If a generated file must be manually patched, document that in README.md, summary.md, or metadata.json and state whether the generator is stale.

• Save validation steps that were performed, such as SQL row counts, JavaScript syntax checks, local render checks, or browser viewing notes.

For interactive HTML artifacts, include viewing instructions when browser security context may matter. For example:

cd path/to/artifact-directory
python3 -m http.server 8000

Then open http://localhost:8000/chart.html instead of relying on file:// behavior.

If a lightweight chart evolves into a reusable or report-ready asset, upgrade the artifact package with a human-readable README.md that includes:

• question and short answer

• metric definition and definition provenance

• source model/table and SQL/query notes

• time window, grain, filters, and exclusions

• artifact inventory

• caveats and sensitivity notes

• validation performed

• reproduce/refresh instructions

README template

# Analysis title

Question: ...

Answer: ...

How I measured it:
- Metric: ...
- Population: ...
- Grain/window: ...
- Filters/exclusions: ...
- Source model/table: ...

Artifacts:
- `query.sql` — final query
- `result.csv` — result snapshot
- `summary.md` — findings and caveats
- `chart.html` / `chart.png` — visualization, if generated

Caveats:
- ...

Reproduce:
1. ...

Metadata fields

When creating metadata.json, include fields like:

{
  "title": "Active users trend",
  "created_at": "2026-05-27T15:40:00-07:00",
  "question": "...",
  "time_window": "...",
  "grain": "...",
  "models": ["..."],
  "metrics": ["..."],
  "filters": ["..."],
  "caveats": ["..."],
  "artifacts": ["query.sql", "result.csv", "summary.md", "chart.html"]
}

Safety and privacy

• Avoid persisting sensitive raw rows unless they are necessary and explicitly requested.

• Prefer aggregate, sampled, redacted, or anonymized outputs for shareable artifacts.

• Make caveats visible next to exported numbers and charts.

• Do not publish or upload artifacts to external services unless the user explicitly asks.

• If storing in a shared repository, avoid secrets, credentials, private customer data, and overly broad raw exports.

Output reporting

After saving artifacts, report:

• absolute or workspace-relative paths

• what each artifact contains

• any sensitivity caveats

• how to reproduce or refresh the analysis

Boundaries

This skill does not replace a BI tool, governed dashboards, documented metric definitions, or a source-of-truth reporting system. Treat persisted artifacts as snapshots unless they are backed by documented models and an agreed refresh process.