explain-dataset-shared

Files (12)

• SKILL.md
• VERSION
• api-fallback.md · references/
• deep-dives.md · references/
• list_unassigned.py · scripts/
• model_config.py · scripts/
• resource_metrics.py · scripts/
• score_justifications.py · scripts/
• score_violations.py · scripts/
• summarize.py · scripts/
• timefold_api.py · scripts/
• work_details.py · scripts/

SKILL.md (first lines)

# Explain Dataset: shared instructions

This file contains the full workflow for explaining an optimized Timefold dataset.
It is model-agnostic. The model-specific SKILL.md you read before this one defines:
- **Terminology**: what "work item" and "resource" mean for this model
- **Model-specific configuration**: `MODEL_API_URL`, `COLLECTION`, and `MODEL` values to pass to scripts
- **Docs URL** for metric definitions

When instructions below say "work item" or "resource", substitute the model-specific terms.

## Language

Everything you write for the user (the chat summary, bottleneck descriptions and proposals,
the coverage headline, the deep-dive offer, and any prose in the written report) should follow
the `language-guidelines` skill: US English, active voice, no em dashes, contractions welcome but
not required, serial commas, numbers one through ten spelled out, and so on. Don't restate those
rules here; just apply them.

`language-guidelines` ships in this plugin, next to this skill. Read
`../language-guidelines/SKILL.md` if it isn't already loaded. If you genuinely cannot reach it,
don't silently skip this or guess at the rules. Tell the user once, early in the conversation:
"I couldn't find the `language-guidelines` skill, so this report won't follow Timefold's language
guidelines automatically." Then proceed with plain, clear writing on your own judgment.

## Environment: find a runtime first

The scripts need nothing more than Python 3.9 or later. They use the standard library only, so
there is no package to install and no virtual environment to create.

**Run this check once, before Step 1.** It prints the runner to use for every script command in
this skill. This skill calls it `$PY`:

```bash
PY=""
uv --version >/dev/null 2>&1 && PY="uv run"
if [ -z "$PY" ]; then
  for c in python3 python; do
    "$c" -c 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else 1)' 2>/dev/null \
      && PY="$c" && break
  done
fi
echo "runner: ${PY:-none}"
```

The loop runs the candidate, and it does not only look for the name. This matters on Windows,
where `python` can be a Microsoft Store stub that is on the PATH but does not work.

**Write the runner out in every command.** Do not rely on `$PY`, `$SCRIPTS`, or any other variable
from an earlier command. Each command starts a new shell, so the variable is gone. And in zsh, the
default shell on macOS, `$PY` with the value `uv run` stays one word, so the command is not found.
Write, for example:

```bash
uv run /abs/path/to/explain-dataset-shared/scripts/summarize.py --model-api-url https://... --model ...
```

In the rest of this skill, `$PY`, `$SCRIPTS`, `$SHARED`, `$PLUGIN_ROOT`, `$MODEL_API_URL`, and
`$MODEL` are placeholders for those values.

If a runner is found, use the scripts. They are faster, they handle pagination and formatting,
and they are the correct choice for any dataset with more than ~50 resources or ~200 work items.

**If no runner is found, do not stop and do not ask the user to install Python.** Drop to the
next level of this ladder:

| Level | Condition | What to do |
|---|---|---|
| 1 | `uv` is on the PATH | The runner is `uv run`, and uv downloads a Python if necessary |
| 2 | Python 3.9+ is on the PATH | The runner is `python3` or `python` |
| 3 | Bash works, but no Python | Call the API with `curl`; see `references/api-fallback.md` |
| 4 | No shell at all | Call the API with WebFetch; see `references/api-fallback.md` |

`curl` is present on macOS, on Linux, and on Windows 10 and later, so level 3 works almost
everywhere. Level 4 covers Claude Desktop without a shell MCP, and the Web UI.

**uv is not a prerequisite.** It is only the best level. Level 2 needs no installation on almost
every macOS and Linux machine, and levels 3 and 4 answer the same questions without Python. Never
tell the user that something is missing before you have tried all four levels.

**Tell the user which level you use, once, at the start.** At level 3 or 4 add this:

> "I don't see Python here, so I'll call the Timefold API directly. That works, but on a large
> dataset it is slower and I can miss detail."

**At level 3, offer to install uv. Do not install it without a yes.** The installer downloads and
runs a script from the internet, so the user decides. Show the command that applies to their
system, and continue at level 3 if they decline or do not answer:

> "Optional: if you install uv, I can use the local scripts instead, which is faster and keeps
> large payloads out of this conversation. It is one binary, it needs no administrator rights,
> and it changes nothing about your system Python. Shall I run this?
>   macOS and Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
>   Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
> Otherwise I'll carry on calling the API directly, which works fine."

The installer puts `uv` in `~/.local/bin`, which the current shell may not have on its PATH. After
an install, use `$HOME/.local/bin/uv run` as the runner for this session rather than starting a new
shell.

**Recommend Claude Code for large datasets.** If the user is on Desktop or Web and the dataset
has hundreds of resources or thousands of work items, tell them upfront:

> "For a dataset this size I'd recommend running this skill in Claude Code. It uses local
> Python scripts that handle large responses efficiently. In this environment I'll call the
> API directly, but parsing very large JSON in context can be slow and may miss detail."

## Scripts (levels 1 and 2)

All scripts live in this skill's own `scripts/` directory. The model-specific skill you read
first tells you the absolute path as `$SCRIPTS`.

| Script | Purpose |
|---|---|
| `summarize.py` | **Start here.** Coverage KPIs, validation warnings, dataset configuration overrides, resource overview |
| `list_unassigned.py` | Unassigned work items with input details; `--recommendations` for bulk API hints |
| `resource_metrics.py` | Per-resource metrics table; `--sort` to rank by overtime / travel / etc. |
| `work_details.py` | Look up specific work items by ID; or all items for `--resource NAME` |
| `score_violations.py` | Constraint violation counts and samples: quick overview of what broke |
| `score_justifications.py` | **Deep dive into justifications.** `--samples N` for a broad overview; `--resource NAME` to see every constraint violation involving a specific vehicle / employee / driver |

From TimefoldAI/skills, Apache-2.0.

More from TimefoldAI/skills