Optimize Mock Data

Optimize Mock Data

Audit and normalize a set of related JSON (or JSONL) mock fixtures so every file shares the same shape, formatting, and verbosity budget. Pure shape work — never touches semantics or business values unless the user explicitly asks for shrink.

This SKILL.md is a thin index. Detailed rules live in rules/*.md and load on demand. Reusable Python scripts live in scripts/*.py and run via Bash. Worked example output lives in references/example-report.md.

Mode Detection

Parse $ARGUMENTS as <mode> <path> [flags] where <mode> is one of analyze, normalize, shrink, trim. If the first token is a path (starts with /, ./, or ~) treat it as <path> and default <mode> to analyze.

State the detected mode, target path, and file count in one line before continuing:

Mode: analyze
Target: components/ui/src/agent0/mocks/ (22 files)

Workflow

A four-phase pipeline. Each phase has a gate; do not proceed until it passes.

Phase 0 — Resolve corpus

1. If <path> is a directory: glob **/*.json and **/*.jsonl (exclude node_modules/, dist/, .next/, coverage/).
2. If <path> is a single file: include it plus all siblings matching the same basename pattern — e.g. invoke-agent-artifacts-dashboards-4.json expands to invoke-agent-artifacts-dashboards*.json in the same directory. The user almost always means "this file and its peers".
3. If fewer than 2 files resolve, halt — single-file optimization is npx prettier --write territory, not this skill's job.

State the resolved corpus before continuing:

Resolved 4 peer files for invoke-agent-artifacts-dashboards-4.json:
  - invoke-agent-artifacts-dashboards.json
  - invoke-agent-artifacts-dashboards-2.json
  - invoke-agent-artifacts-dashboards-3.json
  - invoke-agent-artifacts-dashboards-4.json

Phase 1 — Shape extraction

Run scripts/shape.py on each file. Each file gets a deterministic shape fingerprint — a sorted, recursive type signature where:

• Object keys are sorted alphabetically.
• Values become their type (string, number, boolean, null, object{...}, array[T]).
• Heterogeneous arrays collapse to array[union[T1, T2, ...]].
• Leaf string values are not in the signature — only types.

See rules/shape-extraction.md for the algorithm, the optionality rules, and the JSON Schema mapping.

Phase 2 — Drift detection

Run scripts/diff-shapes.py over every fingerprint pair. Cluster files by fingerprint. For each cluster:

• Majority cluster (the most common shape) becomes the reference.
• Outlier clusters are reported as drift, scored by edit distance.
• For each outlier, list the key paths that differ (messages[].userId present in 18 files, missing in 4).

Output the drift report — see rules/drift-detection.md for the report format and severity rubric. The exact format used in analyze mode is in references/example-report.md.

Phase 3 — Apply (mode-gated)

After every write, re-parse the file to verify it is still valid JSON and re-run Phase 1 against the corpus. If post-rewrite drift is worse than pre-rewrite drift, revert all writes and halt — this means the scripts have a bug or the policy is wrong for this corpus.

Required Reading by Phase

Load on demand — do not preload.

Worked output examples in references/example-report.md are optional — load only when the user asks "what does the report look like?".

Reusable scripts

All scripts are pure Python 3 with stdlib only. No pip install required. They read from stdin or paths, write to stdout, and exit non-zero on shape-validation failure. Run them from the repo root.

Invocation pattern (run from the repo root, scripts are relative to this skill directory):

SKILL_DIR="$HOME/.claude/skills/optimize-mock-data"
python3 "$SKILL_DIR/scripts/shape.py" path/to/mock.json
python3 "$SKILL_DIR/scripts/diff-shapes.py" path/to/mocks/
python3 "$SKILL_DIR/scripts/normalize.py" --in-place path/to/mock.json
python3 "$SKILL_DIR/scripts/shrink.py" --max-string 200 --in-place path/to/mock.json
python3 "$SKILL_DIR/scripts/trim.py" --in-place path/to/mock.json

Core Principles

1. Shape, not semantics. This skill normalizes structure and formatting. It never edits business values (the content of a message, the name of a thread) unless shrink is explicit.
2. Majority wins. When clusters disagree, the largest cluster is the reference. Tie-breaker is the most recently modified file.
3. Round-trip safety. Every rewritten file must parse back into the same Python object after canonicalization. If not, revert.
4. Idempotent. Running normalize twice changes nothing the second time. Running shrink twice with the same threshold changes nothing the second time.
5. No network, no deps. Scripts use stdlib only so they run in any sandbox, CI, or pre-commit hook.

Anti-patterns

• Editing the value of a field ("role": "human" → "role": "user") in normalize mode. Shape work only.
• Sorting array elements. Arrays are ordered; only object keys are sorted.
• Truncating an *Id or hash field. Identifiers are load-bearing for fixture lookups even in tests.
• Treating a .jsonl file as a single JSON document. JSONL is newline-delimited; each line is a separate fingerprint.
• Inferring a schema from one file. Need ≥ 2 to detect drift.
• Trimming arrays outside artifacts.*. Top-level conversation arrays ($.messages, $.thread.*) are off-limits to trim. trim only descends into artifacts.* subtrees.
• Trimming a structural array (panels, widgets, queries). Those describe the dashboard's shape, not data points. The allowlist is strict by design — do not add a default fallback budget that would catch them.
• Modifying any string inside trim. The mode is array-cardinality only. content, panel descriptions, tool arguments — every string round-trips byte-identical. Use shrink if string truncation is wanted.

Definition of Done

• Corpus resolved to ≥ 2 files with a state line printed.
• Every file has a fingerprint.
• Drift report produced (clusters listed, outlier key paths enumerated, severity assigned).
• If normalize or shrink: every rewritten file re-parses and post-rewrite drift ≤ pre-rewrite drift.
• Final one-line summary: N files / M clusters / K drift sites (severity HIGH/MED/LOW).

Diagnosable

This skill declares a diagnostic surface at rules/diagnostic-surface.md — phase model, failure taxonomy (F-novel-seeded), existing-guards table, and hard invariants. Run /create-skill diagnose optimize-mock-data after a failed or unsatisfactory run to get a confidence-gated unified diff that hardens the skill against the same failure class.