/shinka-inspect

name: shinka-inspect
description: Load top-performing Shinka programs into agent context using `shinka.utils.load_programs_to_df`, and emit a compact Markdown bundle for iteration planning.

Shinka Inspect Skill

Extract the strongest programs from a Shinka run and package them into a context file that coding agents can load directly.

When to Use

Use this skill when:

• A run already produced a results directory and SQLite database
• You want to inspect top-performing programs before launching the next batch
• You want a compact context artifact instead of manually browsing the DB

Do not use this skill when:

• You still need to scaffold a task (`shinka-setup`)
• You need to run evolution batches (`shinka-run`)

What it does

• Uses `shinka.utils.load_programs_to_df` to read program records
• Ranks programs by `combined_score`
• Selects top-`k` correct programs (fallback to top-`k` overall if no correct rows)
• Writes one Markdown bundle with metadata, ranking table, feedback, and code snippets

Workflow

1. Confirm run artifacts exist

ls -la <results_dir>

2. Generate context bundle

python skills/shinka-inspect/scripts/inspect_best_programs.py \
  --results-dir <results_dir> \
  --k 5

3. Optional tuning knobs

python skills/shinka-inspect/scripts/inspect_best_programs.py \
  --results-dir <results_dir> \
  --k 8 \
  --max-code-chars 5000 \
  --min-generation 10 \
  --out <results_dir>/inspect/top_programs.md

4. Load output into agent context

• Default output path: `<results_dir>/shinka_inspect_context.md`
• Use it as the context artifact for next-step mutation planning

CLI Arguments

• `--results-dir`: Path to run directory (or direct DB file path)
• `--k`: Number of programs to include (default `5`)
• `--out`: Output markdown path (default under results dir)
• `--max-code-chars`: Per-program code truncation cap (default `4000`)
• `--min-generation`: Optional lower bound on generation
• `--include-feedback` / `--no-include-feedback`: Include `text_feedback` blocks

Notes

• Ranking metric is `combined_score`.
• If no correct rows exist, script falls back to top-score rows and labels fallback in output.
• Script is read-only for run artifacts (writes only the markdown bundle).