yequanzheng

---
name: githubdescription: 这是我的测试32323
---

# GitHub Skill

Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.

## Pull Requests

Check CI status on a PR:
```bash
gh pr checks 55 --repo owner/repo
```

List recent workflow runs:
```bash
gh run list --repo owner/repo --limit 10
```

View a run and see which steps failed:
```bash
gh run view <run-id> --repo owner/repo
```

View logs for failed steps only:
```bash
gh run view <run-id> --repo owner/repo --log-failed
```

## API for Advanced Queries

The `gh api` command is useful for accessing data not available through other subcommands.

Get PR with specific fields:
```bash
gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
```

## JSON Output

Most commands support `--json` for structured output.  You can use `--jq` to filter:

```bash
gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
```

---
name: githubdescription: 这是我的测试32323
---

# GitHub Skill

Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.

## Pull Requests

Check CI status on a PR:
```bash
gh pr checks 55 --repo owner/repo
```

List recent workflow runs:
```bash
gh run list --repo owner/repo --limit 10
```

View a run and see which steps failed:
```bash
gh run view <run-id> --repo owner/repo
```

View logs for failed steps only:
```bash
gh run view <run-id> --repo owner/repo --log-failed
```

## API for Advanced Queries

The `gh api` command is useful for accessing data not available through other subcommands.

Get PR with specific fields:
```bash
gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
```

## JSON Output

Most commands support `--json` for structured output.  You can use `--jq` to filter:

```bash
gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
```

---
name: github
description: 这是我的测试32323
---

# GitHub Skill

Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.

## Pull Requests

Check CI status on a PR:
```bash
gh pr checks 55 --repo owner/repo
```

List recent workflow runs:
```bash
gh run list --repo owner/repo --limit 10
```

View a run and see which steps failed:
```bash
gh run view <run-id> --repo owner/repo
```

View logs for failed steps only:
```bash
gh run view <run-id> --repo owner/repo --log-failed
```

## API for Advanced Queries

The `gh api` command is useful for accessing data not available through other subcommands.

Get PR with specific fields:
```bash
gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
```

## JSON Output

Most commands support `--json` for structured output.  You can use `--jq` to filter:

```bash
gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
```

---
name: githubdescription: 
---

# GitHub Skill

Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.

## Pull Requests

Check CI status on a PR:
```bash
gh pr checks 55 --repo owner/repo
```

List recent workflow runs:
```bash
gh run list --repo owner/repo --limit 10
```

View a run and see which steps failed:
```bash
gh run view <run-id> --repo owner/repo
```

View logs for failed steps only:
```bash
gh run view <run-id> --repo owner/repo --log-failed
```

## API for Advanced Queries

The `gh api` command is useful for accessing data not available through other subcommands.

Get PR with specific fields:
```bash
gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
```

## JSON Output

Most commands support `--json` for structured output.  You can use `--jq` to filter:

```bash
gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
```

---
name: skill-creator
description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
---

# Skill Creator

A skill for creating new skills and iteratively improving them.

At a high level, the process of creating a skill goes like this:

- Decide what you want the skill to do and roughly how it should do it
- Write a draft of the skill
- Create a few test prompts and run claude-with-access-to-the-skill on them
- Help the user evaluate the results both qualitatively and quantitatively
  - While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
  - Use the `eval-viewer/generate_review.py` script to show the user the results for them to look at, and also let them look at the quantitative metrics
- Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks)
- Repeat until you're satisfied
- Expand the test set and try again at larger scale

Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat.

On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop.

Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.

Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill.

Cool? Cool.

## Communicating with the user

The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.

So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:

- "evaluation" and "benchmark" are borderline, but OK
- for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them

It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it.

---

## Creating a skill

### Capture Intent

Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.

1. What should this skill enable Claude to do?
2. When should this skill trigger? (what user phrases/contexts)
3. What's the expected output format?
4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.

### Interview and Research

Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.

Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user.

### Write the SKILL.md

Based on the user interview, fill in these components:

- **name**: Skill identifier
- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
- **compatibility**: Required tools, dependencies (optional, rarely needed)
- **the rest of the skill :)**

### Skill Writing Guide

#### Anatomy of a Skill

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)
```

#### Progressive Disclosure

Skills use a three-level loading system:
1. **Metadata** (name + description) - Always in context (~100 words)
2. **SKILL.md body** - In context whenever skill triggers (<500 lines ideal)
3. **Bundled resources** - As needed (unlimited, scripts can execute without loading)

These word counts are approximate and you can feel free to go longer if needed.

**Key patterns:**
- Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
- Reference files clearly from SKILL.md with guidance on when to read them
- For large reference files (>300 lines), include a table of contents

**Domain organization**: When a skill supports multiple domains/frameworks, organize by variant:
```
cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```
Claude reads only the relevant reference file.

#### Principle of Lack of Surprise

This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though.

#### Writing Patterns

Prefer using the imperative form in instructions.

**Defining output formats** - You can do it like this:
```markdown
## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations
```

**Examples pattern** - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little):
```markdown
## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication
```

### Writing Style

Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it.

### Test Cases

After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: [you don't have to use this exact language] "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them.

Save test cases to `evals/evals.json`. Don't write assertions yet — just the prompts. You'll draft assertions in the next step while the runs are in progress.

```json
{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}
```

See `references/schemas.md` for the full schema (including the `assertions` field, which you'll add later).

## Running and evaluating test cases

This section is one continuous sequence — don't stop partway through. Do NOT use `/skill-test` or any other testing skill.

Put results in `<skill-name>-workspace/` as a sibling to the skill directory. Within the workspace, organize results by iteration (`iteration-1/`, `iteration-2/`, etc.) and within that, each test case gets a directory (`eval-0/`, `eval-1/`, etc.). Don't create all of this upfront — just create directories as you go.

### Step 1: Spawn all runs (with-skill AND baseline) in the same turn

For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time.

**With-skill run:**

```
Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">
```

**Baseline run** (same prompt, but the baseline depends on context):
- **Creating a new skill**: no skill at all. Same prompt, no skill path, save to `without_skill/outputs/`.
- **Improving an existing skill**: the old version. Before editing, snapshot the skill (`cp -r <skill-path> <workspace>/skill-snapshot/`), then point the baseline subagent at the snapshot. Save to `old_skill/outputs/`.

Write an `eval_metadata.json` for each test case (assertions can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations.

```json
{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}
```

### Step 2: While runs are in progress, draft assertions

Don't just wait for the runs to finish — you can use this time productively. Draft quantitative assertions for each test case and explain them to the user. If assertions already exist in `evals/evals.json`, review them and explain what they check.

Good assertions are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force assertions onto things that need human judgment.

Update the `eval_metadata.json` files and `evals/evals.json` with the assertions once drafted. Also explain to the user what they'll see in the viewer — both the qualitative outputs and the quantitative benchmark.

### Step 3: As runs complete, capture timing data

When each subagent task completes, you receive a notification containing `total_tokens` and `duration_ms`. Save this data immediately to `timing.json` in the run directory:

```json
{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}
```

This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them.

### Step 4: Grade, aggregate, and launch the viewer

Once all runs are done:

1. **Grade each run** — spawn a grader subagent (or grade inline) that reads `agents/grader.md` and evaluates each assertion against the outputs. Save results to `grading.json` in each run directory. The grading.json expectations array must use the fields `text`, `passed`, and `evidence` (not `name`/`met`/`details` or other variants) — the viewer depends on these exact field names. For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations.

2. **Aggregate into benchmark** — run the aggregation script from the skill-creator directory:
   ```bash
   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   ```
   This produces `benchmark.json` and `benchmark.md` with pass_rate, time, and tokens for each configuration, with mean ± stddev and the delta. If generating benchmark.json manually, see `references/schemas.md` for the exact schema the viewer expects.
Put each with_skill version before its baseline counterpart.

3. **Do an analyst pass** — read the benchmark data and surface patterns the aggregate stats might hide. See `agents/analyzer.md` (the "Analyzing Benchmark Results" section) for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals (possibly flaky), and time/token tradeoffs.

4. **Launch the viewer** with both qualitative outputs and quantitative data:
   ```bash
   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   ```
   For iteration 2+, also pass `--previous-workspace <workspace>/iteration-<N-1>`.

   **Cowork / headless environments:** If `webbrowser.open()` is not available or the environment has no display, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a `feedback.json` file when the user clicks "Submit All Reviews". After download, copy `feedback.json` into the workspace directory for the next iteration to pick up.

Note: please use generate_review.py to create the viewer; there's no need to write custom HTML.

5. **Tell the user** something like: "I've opened the results in your browser. There are two tabs — 'Outputs' lets you click through each test case and leave feedback, 'Benchmark' shows the quantitative comparison. When you're done, come back here and let me know."

### What the user sees in the viewer

The "Outputs" tab shows one test case at a time:
- **Prompt**: the task that was given
- **Output**: the files the skill produced, rendered inline where possible
- **Previous Output** (iteration 2+): collapsed section showing last iteration's output
- **Formal Grades** (if grading was run): collapsed section showing assertion pass/fail
- **Feedback**: a textbox that auto-saves as they type
- **Previous Feedback** (iteration 2+): their comments from last time, shown below the textbox

The "Benchmark" tab shows the stats summary: pass rates, timing, and token usage for each configuration, with per-eval breakdowns and analyst observations.

Navigation is via prev/next buttons or arrow keys. When done, they click "Submit All Reviews" which saves all feedback to `feedback.json`.

### Step 5: Read the feedback

When the user tells you they're done, read `feedback.json`:

```json
{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}
```

Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints.

Kill the viewer server when you're done with it:

```bash
kill $VIEWER_PID 2>/dev/null
```

---

## Improving the skill

This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback.

### How to think about improvements

1. **Generalize from the feedback.** The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you and the user are iterating on only a few examples over and over again because it helps move faster. The user knows these examples in and out and it's quick for them to assess new outputs. But if the skill you and the user are codeveloping works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great.

2. **Keep the prompt lean.** Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens.

3. **Explain the why.** Try hard to explain the **why** behind everything you're asking the model to do. Today's LLMs are *smart*. They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback from the user is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach.

4. **Look for repeated work across test cases.** Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a `create_docx.py` or a `build_chart.py`, that's a strong signal the skill should bundle that script. Write it once, put it in `scripts/`, and tell the skill to use it. This saves every future invocation from reinventing the wheel.

This task is pretty important (we are trying to create billions a year in economic value here!) and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need.

### The iteration loop

After improving the skill:

1. Apply your improvements to the skill
2. Rerun all test cases into a new `iteration-<N+1>/` directory, including baseline runs. If you're creating a new skill, the baseline is always `without_skill` (no skill) — that stays the same across iterations. If you're improving an existing skill, use your judgment on what makes sense as the baseline: the original version the user came in with, or the previous iteration.
3. Launch the reviewer with `--previous-workspace` pointing at the previous iteration
4. Wait for the user to review and tell you they're done
5. Read the new feedback, improve again, repeat

Keep going until:
- The user says they're happy
- The feedback is all empty (everything looks good)
- You're not making meaningful progress

---

## Advanced: Blind comparison

For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read `agents/comparator.md` and `agents/analyzer.md` for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won.

This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient.

---

## Description Optimization

The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.

### Step 1: Generate trigger eval queries

Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:

```json
[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]
```

The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).

Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"`

Good: `"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"`

For the **should-trigger** queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win.

For the **should-not-trigger** queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate.

The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky.

### Step 2: Review with user

Present the eval set to the user for review using the HTML template:

1. Read the template from `assets/eval_review.html`
2. Replace the placeholders:
   - `__EVAL_DATA_PLACEHOLDER__` → the JSON array of eval items (no quotes around it — it's a JS variable assignment)
   - `__SKILL_NAME_PLACEHOLDER__` → the skill's name
   - `__SKILL_DESCRIPTION_PLACEHOLDER__` → the skill's current description
3. Write to a temp file (e.g., `/tmp/eval_review_<skill-name>.html`) and open it: `open /tmp/eval_review_<skill-name>.html`
4. The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set"
5. The file downloads to `~/Downloads/eval_set.json` — check the Downloads folder for the most recent version in case there are multiple (e.g., `eval_set (1).json`)

This step matters — bad eval queries lead to bad descriptions.

### Step 3: Run the optimization loop

Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically."

Save the eval set to the workspace, then run in the background:

```bash
python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose
```

Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.

While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.

This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting.

### How skill triggering works

Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's `available_skills` list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.

This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.

### Step 4: Apply the result

Take `best_description` from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores.

---

### Package and Present (only if `present_files` tool is available)

Check whether you have access to the `present_files` tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user:

```bash
python -m scripts.package_skill <path/to/skill-folder>
```

After packaging, direct the user to the resulting `.skill` file path so they can install it.

---

## Claude.ai-specific instructions

In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt:

**Running test cases**: No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested.

**Reviewing results**: If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?"

**Benchmarking**: Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user.

**The iteration loop**: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one.

**Description optimization**: This section requires the `claude` CLI tool (specifically `claude -p`) which is only available in Claude Code. Skip it if you're on Claude.ai.

**Blind comparison**: Requires subagents. Skip it.

**Packaging**: The `package_skill.py` script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting `.skill` file.

**Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. In this case:
- **Preserve the original name.** Note the skill's directory name and `name` frontmatter field -- use them unchanged. E.g., if the installed skill is `research-helper`, output `research-helper.skill` (not `research-helper-v2`).
- **Copy to a writeable location before editing.** The installed skill path may be read-only. Copy to `/tmp/skill-name/`, edit there, and package from the copy.
- **If packaging manually, stage in `/tmp/` first**, then copy to the output directory -- direct writes may fail due to permissions.

---

## Cowork-Specific Instructions

If you're in Cowork, the main things to know are:

- You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.)
- You don't have a browser or display, so when generating the eval viewer, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser.
- For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using `generate_review.py` (not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER *BEFORE* evaluating inputs yourself. You want to get them in front of the human ASAP!
- Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download `feedback.json` as a file. You can then read it from there (you may have to request access first).
- Packaging works — `package_skill.py` just needs Python and a filesystem.
- Description optimization (`run_loop.py` / `run_eval.py`) should work in Cowork just fine since it uses `claude -p` via subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape.
- **Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above.

---

## Reference files

The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent.

- `agents/grader.md` — How to evaluate assertions against outputs
- `agents/comparator.md` — How to do blind A/B comparison between two outputs
- `agents/analyzer.md` — How to analyze why one version beat another

The references/ directory has additional documentation:
- `references/schemas.md` — JSON structures for evals.json, grading.json, etc.

---

Repeating one more time the core loop here for emphasis:

- Figure out what the skill is about
- Draft or edit the skill
- Run claude-with-access-to-the-skill on test prompts
- With the user, evaluate the outputs:
  - Create benchmark.json and run `eval-viewer/generate_review.py` to help the user review them
  - Run quantitative evals
- Repeat until you and the user are satisfied
- Package the final skill and return it to the user.

Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" in your TodoList to make sure it happens.

Good luck!

FILE:LICENSE.txt

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
FILE:assets/eval_review.html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Eval Set Review - __SKILL_NAME_PLACEHOLDER__</title>
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
  <style>
    * { box-sizing: border-box; margin: 0; padding: 0; }
    body { font-family: 'Lora', Georgia, serif; background: #faf9f5; padding: 2rem; color: #141413; }
    h1 { font-family: 'Poppins', sans-serif; margin-bottom: 0.5rem; font-size: 1.5rem; }
    .description { color: #b0aea5; margin-bottom: 1.5rem; font-style: italic; max-width: 900px; }
    .controls { margin-bottom: 1rem; display: flex; gap: 0.5rem; }
    .btn { font-family: 'Poppins', sans-serif; padding: 0.5rem 1rem; border: none; border-radius: 6px; cursor: pointer; font-size: 0.875rem; font-weight: 500; }
    .btn-add { background: #6a9bcc; color: white; }
    .btn-add:hover { background: #5889b8; }
    .btn-export { background: #d97757; color: white; }
    .btn-export:hover { background: #c4613f; }
    table { width: 100%; max-width: 1100px; border-collapse: collapse; background: white; border-radius: 6px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.08); }
    th { font-family: 'Poppins', sans-serif; background: #141413; color: #faf9f5; padding: 0.75rem 1rem; text-align: left; font-size: 0.875rem; }
    td { padding: 0.75rem 1rem; border-bottom: 1px solid #e8e6dc; vertical-align: top; }
    tr:nth-child(even) td { background: #faf9f5; }
    tr:hover td { background: #f3f1ea; }
    .section-header td { background: #e8e6dc; font-family: 'Poppins', sans-serif; font-weight: 500; font-size: 0.8rem; color: #141413; text-transform: uppercase; letter-spacing: 0.05em; }
    .query-input { width: 100%; padding: 0.4rem; border: 1px solid #e8e6dc; border-radius: 4px; font-size: 0.875rem; font-family: 'Lora', Georgia, serif; resize: vertical; min-height: 60px; }
    .query-input:focus { outline: none; border-color: #d97757; box-shadow: 0 0 0 2px rgba(217,119,87,0.15); }
    .toggle { position: relative; display: inline-block; width: 44px; height: 24px; }
    .toggle input { opacity: 0; width: 0; height: 0; }
    .toggle .slider { position: absolute; inset: 0; background: #b0aea5; border-radius: 24px; cursor: pointer; transition: 0.2s; }
    .toggle .slider::before { content: ""; position: absolute; width: 18px; height: 18px; left: 3px; bottom: 3px; background: white; border-radius: 50%; transition: 0.2s; }
    .toggle input:checked + .slider { background: #d97757; }
    .toggle input:checked + .slider::before { transform: translateX(20px); }
    .btn-delete { background: #c44; color: white; padding: 0.3rem 0.6rem; border: none; border-radius: 4px; cursor: pointer; font-size: 0.75rem; font-family: 'Poppins', sans-serif; }
    .btn-delete:hover { background: #a33; }
    .summary { margin-top: 1rem; color: #b0aea5; font-size: 0.875rem; }
  </style>
</head>
<body>
  <h1>Eval Set Review: <span id="skill-name">__SKILL_NAME_PLACEHOLDER__</span></h1>
  <p class="description">Current description: <span id="skill-desc">__SKILL_DESCRIPTION_PLACEHOLDER__</span></p>

  <div class="controls">
    <button class="btn btn-add" onclick="addRow()">+ Add Query</button>
    <button class="btn btn-export" onclick="exportEvalSet()">Export Eval Set</button>
  </div>

  <table>
    <thead>
      <tr>
        <th style="width:65%">Query</th>
        <th style="width:18%">Should Trigger</th>
        <th style="width:10%">Actions</th>
      </tr>
    </thead>
    <tbody id="eval-body"></tbody>
  </table>

  <p class="summary" id="summary"></p>

  <script>
    const EVAL_DATA = __EVAL_DATA_PLACEHOLDER__;

    let evalItems = [...EVAL_DATA];

    function render() {
      const tbody = document.getElementById('eval-body');
      tbody.innerHTML = '';

      // Sort: should-trigger first, then should-not-trigger
      const sorted = evalItems
        .map((item, origIdx) => ({ ...item, origIdx }))
        .sort((a, b) => (b.should_trigger ? 1 : 0) - (a.should_trigger ? 1 : 0));

      let lastGroup = null;
      sorted.forEach(item => {
        const group = item.should_trigger ? 'trigger' : 'no-trigger';
        if (group !== lastGroup) {
          const headerRow = document.createElement('tr');
          headerRow.className = 'section-header';
          headerRow.innerHTML = `<td colspan="3">'Should NOT Trigger'</td>`;
          tbody.appendChild(headerRow);
          lastGroup = group;
        }

        const idx = item.origIdx;
        const tr = document.createElement('tr');
        tr.innerHTML = `
          <td><textarea class="query-input" onchange="updateQuery(idx, this.value)">escapeHtml(item.query)</textarea></td>
          <td>
            <label class="toggle">
              <input type="checkbox" '' onchange="updateTrigger(idx, this.checked)">
              <span class="slider"></span>
            </label>
            <span style="margin-left:8px;font-size:0.8rem;color:#b0aea5">'No'</span>
          </td>
          <td><button class="btn-delete" onclick="deleteRow(idx)">Delete</button></td>
        `;
        tbody.appendChild(tr);
      });
      updateSummary();
    }

    function escapeHtml(text) {
      const div = document.createElement('div');
      div.textContent = text;
      return div.innerHTML;
    }

    function updateQuery(idx, value) { evalItems[idx].query = value; updateSummary(); }
    function updateTrigger(idx, value) { evalItems[idx].should_trigger = value; render(); }
    function deleteRow(idx) { evalItems.splice(idx, 1); render(); }

    function addRow() {
      evalItems.push({ query: '', should_trigger: true });
      render();
      const inputs = document.querySelectorAll('.query-input');
      inputs[inputs.length - 1].focus();
    }

    function updateSummary() {
      const trigger = evalItems.filter(i => i.should_trigger).length;
      const noTrigger = evalItems.filter(i => !i.should_trigger).length;
      document.getElementById('summary').textContent =
        `evalItems.length queries total: trigger should trigger, noTrigger should not trigger`;
    }

    function exportEvalSet() {
      const valid = evalItems.filter(i => i.query.trim() !== '');
      const data = valid.map(i => ({ query: i.query.trim(), should_trigger: i.should_trigger }));
      const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
      const url = URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url;
      a.download = 'eval_set.json';
      document.body.appendChild(a);
      a.click();
      document.body.removeChild(a);
      URL.revokeObjectURL(url);
    }

    render();
  </script>
</body>
</html>

FILE:.codebuddy/memory/2026-03-18.md
# 2026-03-18

## 安装 skill-creator
- 从 https://github.com/anthropics/skills/tree/main/skills/skill-creator 克隆并安装到 `/Users/yazi/CodeBuddy/skill/`
- 包含 SKILL.md、agents/、scripts/、references/、assets/、eval-viewer/ 等完整文件

## 创建 daily-menu skill（今日菜单生成器）
- 路径：`/Users/yazi/CodeBuddy/skill/daily-menu/`
- 功能：根据用户食材、口味偏好、人数、时间，智能推荐菜单和烹饪指南
- 文件结构：
  - `SKILL.md` - 技能主文件，定义工作流程和输出格式
  - `references/ingredients.md` - 食材数据库（101种食材，6大分类）
  - `references/recipes.md` - 菜谱库（20道菜，4种风格）
  - `scripts/generate_menu.py` - 菜单匹配生成脚本
  - `evals/evals.json` - 5个评估测试用例
- 支持口味：家常、清淡减脂、快手10分钟、川湘重口
- 脚本已测试通过

FILE:scripts/run_eval.py
#!/usr/bin/env python3
"""Run trigger evaluation for a skill description.

Tests whether a skill's description causes Claude to trigger (read the skill)
for a set of queries. Outputs results as JSON.
"""

import argparse
import json
import os
import select
import subprocess
import sys
import time
import uuid
from concurrent.futures import ProcessPoolExecutor, as_completed
from pathlib import Path

from scripts.utils import parse_skill_md


def find_project_root() -> Path:
    """Find the project root by walking up from cwd looking for .claude/.

    Mimics how Claude Code discovers its project root, so the command file
    we create ends up where claude -p will look for it.
    """
    current = Path.cwd()
    for parent in [current, *current.parents]:
        if (parent / ".claude").is_dir():
            return parent
    return current


def run_single_query(
    query: str,
    skill_name: str,
    skill_description: str,
    timeout: int,
    project_root: str,
    model: str | None = None,
) -> bool:
    """Run a single query and return whether the skill was triggered.

    Creates a command file in .claude/commands/ so it appears in Claude's
    available_skills list, then runs `claude -p` with the raw query.
    Uses --include-partial-messages to detect triggering early from
    stream events (content_block_start) rather than waiting for the
    full assistant message, which only arrives after tool execution.
    """
    unique_id = uuid.uuid4().hex[:8]
    clean_name = f"{skill_name}-skill-{unique_id}"
    project_commands_dir = Path(project_root) / ".claude" / "commands"
    command_file = project_commands_dir / f"{clean_name}.md"

    try:
        project_commands_dir.mkdir(parents=True, exist_ok=True)
        # Use YAML block scalar to avoid breaking on quotes in description
        indented_desc = "\n  ".join(skill_description.split("\n"))
        command_content = (
            f"---\n"
            f"description: |\n"
            f"  {indented_desc}\n"
            f"---\n\n"
            f"# {skill_name}\n\n"
            f"This skill handles: {skill_description}\n"
        )
        command_file.write_text(command_content)

        cmd = [
            "claude",
            "-p", query,
            "--output-format", "stream-json",
            "--verbose",
            "--include-partial-messages",
        ]
        if model:
            cmd.extend(["--model", model])

        # Remove CLAUDECODE env var to allow nesting claude -p inside a
        # Claude Code session. The guard is for interactive terminal conflicts;
        # programmatic subprocess usage is safe.
        env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}

        process = subprocess.Popen(
            cmd,
            stdout=subprocess.PIPE,
            stderr=subprocess.DEVNULL,
            cwd=project_root,
            env=env,
        )

        triggered = False
        start_time = time.time()
        buffer = ""
        # Track state for stream event detection
        pending_tool_name = None
        accumulated_json = ""

        try:
            while time.time() - start_time < timeout:
                if process.poll() is not None:
                    remaining = process.stdout.read()
                    if remaining:
                        buffer += remaining.decode("utf-8", errors="replace")
                    break

                ready, _, _ = select.select([process.stdout], [], [], 1.0)
                if not ready:
                    continue

                chunk = os.read(process.stdout.fileno(), 8192)
                if not chunk:
                    break
                buffer += chunk.decode("utf-8", errors="replace")

                while "\n" in buffer:
                    line, buffer = buffer.split("\n", 1)
                    line = line.strip()
                    if not line:
                        continue

                    try:
                        event = json.loads(line)
                    except json.JSONDecodeError:
                        continue

                    # Early detection via stream events
                    if event.get("type") == "stream_event":
                        se = event.get("event", {})
                        se_type = se.get("type", "")

                        if se_type == "content_block_start":
                            cb = se.get("content_block", {})
                            if cb.get("type") == "tool_use":
                                tool_name = cb.get("name", "")
                                if tool_name in ("Skill", "Read"):
                                    pending_tool_name = tool_name
                                    accumulated_json = ""
                                else:
                                    return False

                        elif se_type == "content_block_delta" and pending_tool_name:
                            delta = se.get("delta", {})
                            if delta.get("type") == "input_json_delta":
                                accumulated_json += delta.get("partial_json", "")
                                if clean_name in accumulated_json:
                                    return True

                        elif se_type in ("content_block_stop", "message_stop"):
                            if pending_tool_name:
                                return clean_name in accumulated_json
                            if se_type == "message_stop":
                                return False

                    # Fallback: full assistant message
                    elif event.get("type") == "assistant":
                        message = event.get("message", {})
                        for content_item in message.get("content", []):
                            if content_item.get("type") != "tool_use":
                                continue
                            tool_name = content_item.get("name", "")
                            tool_input = content_item.get("input", {})
                            if tool_name == "Skill" and clean_name in tool_input.get("skill", ""):
                                triggered = True
                            elif tool_name == "Read" and clean_name in tool_input.get("file_path", ""):
                                triggered = True
                            return triggered

                    elif event.get("type") == "result":
                        return triggered
        finally:
            # Clean up process on any exit path (return, exception, timeout)
            if process.poll() is None:
                process.kill()
                process.wait()

        return triggered
    finally:
        if command_file.exists():
            command_file.unlink()


def run_eval(
    eval_set: list[dict],
    skill_name: str,
    description: str,
    num_workers: int,
    timeout: int,
    project_root: Path,
    runs_per_query: int = 1,
    trigger_threshold: float = 0.5,
    model: str | None = None,
) -> dict:
    """Run the full eval set and return results."""
    results = []

    with ProcessPoolExecutor(max_workers=num_workers) as executor:
        future_to_info = {}
        for item in eval_set:
            for run_idx in range(runs_per_query):
                future = executor.submit(
                    run_single_query,
                    item["query"],
                    skill_name,
                    description,
                    timeout,
                    str(project_root),
                    model,
                )
                future_to_info[future] = (item, run_idx)

        query_triggers: dict[str, list[bool]] = {}
        query_items: dict[str, dict] = {}
        for future in as_completed(future_to_info):
            item, _ = future_to_info[future]
            query = item["query"]
            query_items[query] = item
            if query not in query_triggers:
                query_triggers[query] = []
            try:
                query_triggers[query].append(future.result())
            except Exception as e:
                print(f"Warning: query failed: {e}", file=sys.stderr)
                query_triggers[query].append(False)

    for query, triggers in query_triggers.items():
        item = query_items[query]
        trigger_rate = sum(triggers) / len(triggers)
        should_trigger = item["should_trigger"]
        if should_trigger:
            did_pass = trigger_rate >= trigger_threshold
        else:
            did_pass = trigger_rate < trigger_threshold
        results.append({
            "query": query,
            "should_trigger": should_trigger,
            "trigger_rate": trigger_rate,
            "triggers": sum(triggers),
            "runs": len(triggers),
            "pass": did_pass,
        })

    passed = sum(1 for r in results if r["pass"])
    total = len(results)

    return {
        "skill_name": skill_name,
        "description": description,
        "results": results,
        "summary": {
            "total": total,
            "passed": passed,
            "failed": total - passed,
        },
    }


def main():
    parser = argparse.ArgumentParser(description="Run trigger evaluation for a skill description")
    parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
    parser.add_argument("--skill-path", required=True, help="Path to skill directory")
    parser.add_argument("--description", default=None, help="Override description to test")
    parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
    parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
    parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
    parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
    parser.add_argument("--model", default=None, help="Model to use for claude -p (default: user's configured model)")
    parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
    args = parser.parse_args()

    eval_set = json.loads(Path(args.eval_set).read_text())
    skill_path = Path(args.skill_path)

    if not (skill_path / "SKILL.md").exists():
        print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
        sys.exit(1)

    name, original_description, content = parse_skill_md(skill_path)
    description = args.description or original_description
    project_root = find_project_root()

    if args.verbose:
        print(f"Evaluating: {description}", file=sys.stderr)

    output = run_eval(
        eval_set=eval_set,
        skill_name=name,
        description=description,
        num_workers=args.num_workers,
        timeout=args.timeout,
        project_root=project_root,
        runs_per_query=args.runs_per_query,
        trigger_threshold=args.trigger_threshold,
        model=args.model,
    )

    if args.verbose:
        summary = output["summary"]
        print(f"Results: {summary['passed']}/{summary['total']} passed", file=sys.stderr)
        for r in output["results"]:
            status = "PASS" if r["pass"] else "FAIL"
            rate_str = f"{r['triggers']}/{r['runs']}"
            print(f"  [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:70]}", file=sys.stderr)

    print(json.dumps(output, indent=2))


if __name__ == "__main__":
    main()

FILE:scripts/package_skill.py
#!/usr/bin/env python3
"""
Skill Packager - Creates a distributable .skill file of a skill folder

Usage:
    python utils/package_skill.py <path/to/skill-folder> [output-directory]

Example:
    python utils/package_skill.py skills/public/my-skill
    python utils/package_skill.py skills/public/my-skill ./dist
"""

import fnmatch
import sys
import zipfile
from pathlib import Path
from scripts.quick_validate import validate_skill

# Patterns to exclude when packaging skills.
EXCLUDE_DIRS = {"__pycache__", "node_modules"}
EXCLUDE_GLOBS = {"*.pyc"}
EXCLUDE_FILES = {".DS_Store"}
# Directories excluded only at the skill root (not when nested deeper).
ROOT_EXCLUDE_DIRS = {"evals"}


def should_exclude(rel_path: Path) -> bool:
    """Check if a path should be excluded from packaging."""
    parts = rel_path.parts
    if any(part in EXCLUDE_DIRS for part in parts):
        return True
    # rel_path is relative to skill_path.parent, so parts[0] is the skill
    # folder name and parts[1] (if present) is the first subdir.
    if len(parts) > 1 and parts[1] in ROOT_EXCLUDE_DIRS:
        return True
    name = rel_path.name
    if name in EXCLUDE_FILES:
        return True
    return any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_GLOBS)


def package_skill(skill_path, output_dir=None):
    """
    Package a skill folder into a .skill file.

    Args:
        skill_path: Path to the skill folder
        output_dir: Optional output directory for the .skill file (defaults to current directory)

    Returns:
        Path to the created .skill file, or None if error
    """
    skill_path = Path(skill_path).resolve()

    # Validate skill folder exists
    if not skill_path.exists():
        print(f"❌ Error: Skill folder not found: {skill_path}")
        return None

    if not skill_path.is_dir():
        print(f"❌ Error: Path is not a directory: {skill_path}")
        return None

    # Validate SKILL.md exists
    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        print(f"❌ Error: SKILL.md not found in {skill_path}")
        return None

    # Run validation before packaging
    print("🔍 Validating skill...")
    valid, message = validate_skill(skill_path)
    if not valid:
        print(f"❌ Validation failed: {message}")
        print("   Please fix the validation errors before packaging.")
        return None
    print(f"✅ {message}\n")

    # Determine output location
    skill_name = skill_path.name
    if output_dir:
        output_path = Path(output_dir).resolve()
        output_path.mkdir(parents=True, exist_ok=True)
    else:
        output_path = Path.cwd()

    skill_filename = output_path / f"{skill_name}.skill"

    # Create the .skill file (zip format)
    try:
        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
            # Walk through the skill directory, excluding build artifacts
            for file_path in skill_path.rglob('*'):
                if not file_path.is_file():
                    continue
                arcname = file_path.relative_to(skill_path.parent)
                if should_exclude(arcname):
                    print(f"  Skipped: {arcname}")
                    continue
                zipf.write(file_path, arcname)
                print(f"  Added: {arcname}")

        print(f"\n✅ Successfully packaged skill to: {skill_filename}")
        return skill_filename

    except Exception as e:
        print(f"❌ Error creating .skill file: {e}")
        return None


def main():
    if len(sys.argv) < 2:
        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
        print("\nExample:")
        print("  python utils/package_skill.py skills/public/my-skill")
        print("  python utils/package_skill.py skills/public/my-skill ./dist")
        sys.exit(1)

    skill_path = sys.argv[1]
    output_dir = sys.argv[2] if len(sys.argv) > 2 else None

    print(f"📦 Packaging skill: {skill_path}")
    if output_dir:
        print(f"   Output directory: {output_dir}")
    print()

    result = package_skill(skill_path, output_dir)

    if result:
        sys.exit(0)
    else:
        sys.exit(1)


if __name__ == "__main__":
    main()

FILE:scripts/quick_validate.py
#!/usr/bin/env python3
"""
Quick validation script for skills - minimal version
"""

import sys
import os
import re
import yaml
from pathlib import Path

def validate_skill(skill_path):
    """Basic validation of a skill"""
    skill_path = Path(skill_path)

    # Check SKILL.md exists
    skill_md = skill_path / 'SKILL.md'
    if not skill_md.exists():
        return False, "SKILL.md not found"

    # Read and validate frontmatter
    content = skill_md.read_text()
    if not content.startswith('---'):
        return False, "No YAML frontmatter found"

    # Extract frontmatter
    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if not match:
        return False, "Invalid frontmatter format"

    frontmatter_text = match.group(1)

    # Parse YAML frontmatter
    try:
        frontmatter = yaml.safe_load(frontmatter_text)
        if not isinstance(frontmatter, dict):
            return False, "Frontmatter must be a YAML dictionary"
    except yaml.YAMLError as e:
        return False, f"Invalid YAML in frontmatter: {e}"

    # Define allowed properties
    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}

    # Check for unexpected properties (excluding nested keys under metadata)
    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
    if unexpected_keys:
        return False, (
            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
        )

    # Check required fields
    if 'name' not in frontmatter:
        return False, "Missing 'name' in frontmatter"
    if 'description' not in frontmatter:
        return False, "Missing 'description' in frontmatter"

    # Extract name for validation
    name = frontmatter.get('name', '')
    if not isinstance(name, str):
        return False, f"Name must be a string, got {type(name).__name__}"
    name = name.strip()
    if name:
        # Check naming convention (kebab-case: lowercase with hyphens)
        if not re.match(r'^[a-z0-9-]+$', name):
            return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
        if name.startswith('-') or name.endswith('-') or '--' in name:
            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
        # Check name length (max 64 characters per spec)
        if len(name) > 64:
            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."

    # Extract and validate description
    description = frontmatter.get('description', '')
    if not isinstance(description, str):
        return False, f"Description must be a string, got {type(description).__name__}"
    description = description.strip()
    if description:
        # Check for angle brackets
        if '<' in description or '>' in description:
            return False, "Description cannot contain angle brackets (< or >)"
        # Check description length (max 1024 characters per spec)
        if len(description) > 1024:
            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."

    # Validate compatibility field if present (optional)
    compatibility = frontmatter.get('compatibility', '')
    if compatibility:
        if not isinstance(compatibility, str):
            return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
        if len(compatibility) > 500:
            return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."

    return True, "Skill is valid!"

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python quick_validate.py <skill_directory>")
        sys.exit(1)
    
    valid, message = validate_skill(sys.argv[1])
    print(message)
    sys.exit(0 if valid else 1)
FILE:scripts/improve_description.py
#!/usr/bin/env python3
"""Improve a skill description based on eval results.

Takes eval results (from run_eval.py) and generates an improved description
by calling `claude -p` as a subprocess (same auth pattern as run_eval.py —
uses the session's Claude Code auth, no separate ANTHROPIC_API_KEY needed).
"""

import argparse
import json
import os
import re
import subprocess
import sys
from pathlib import Path

from scripts.utils import parse_skill_md


def _call_claude(prompt: str, model: str | None, timeout: int = 300) -> str:
    """Run `claude -p` with the prompt on stdin and return the text response.

    Prompt goes over stdin (not argv) because it embeds the full SKILL.md
    body and can easily exceed comfortable argv length.
    """
    cmd = ["claude", "-p", "--output-format", "text"]
    if model:
        cmd.extend(["--model", model])

    # Remove CLAUDECODE env var to allow nesting claude -p inside a
    # Claude Code session. The guard is for interactive terminal conflicts;
    # programmatic subprocess usage is safe. Same pattern as run_eval.py.
    env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}

    result = subprocess.run(
        cmd,
        input=prompt,
        capture_output=True,
        text=True,
        env=env,
        timeout=timeout,
    )
    if result.returncode != 0:
        raise RuntimeError(
            f"claude -p exited {result.returncode}\nstderr: {result.stderr}"
        )
    return result.stdout


def improve_description(
    skill_name: str,
    skill_content: str,
    current_description: str,
    eval_results: dict,
    history: list[dict],
    model: str,
    test_results: dict | None = None,
    log_dir: Path | None = None,
    iteration: int | None = None,
) -> str:
    """Call Claude to improve the description based on eval results."""
    failed_triggers = [
        r for r in eval_results["results"]
        if r["should_trigger"] and not r["pass"]
    ]
    false_triggers = [
        r for r in eval_results["results"]
        if not r["should_trigger"] and not r["pass"]
    ]

    # Build scores summary
    train_score = f"{eval_results['summary']['passed']}/{eval_results['summary']['total']}"
    if test_results:
        test_score = f"{test_results['summary']['passed']}/{test_results['summary']['total']}"
        scores_summary = f"Train: {train_score}, Test: {test_score}"
    else:
        scores_summary = f"Train: {train_score}"

    prompt = f"""You are optimizing a skill description for a Claude Code skill called "{skill_name}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that Claude sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples.

The description appears in Claude's "available_skills" list. When a user sends a query, Claude decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones.

Here's the current description:
<current_description>
"{current_description}"
</current_description>

Current scores ({scores_summary}):
<scores_summary>
"""
    if failed_triggers:
        prompt += "FAILED TO TRIGGER (should have triggered but didn't):\n"
        for r in failed_triggers:
            prompt += f'  - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n'
        prompt += "\n"

    if false_triggers:
        prompt += "FALSE TRIGGERS (triggered but shouldn't have):\n"
        for r in false_triggers:
            prompt += f'  - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n'
        prompt += "\n"

    if history:
        prompt += "PREVIOUS ATTEMPTS (do NOT repeat these — try something structurally different):\n\n"
        for h in history:
            train_s = f"{h.get('train_passed', h.get('passed', 0))}/{h.get('train_total', h.get('total', 0))}"
            test_s = f"{h.get('test_passed', '?')}/{h.get('test_total', '?')}" if h.get('test_passed') is not None else None
            score_str = f"train={train_s}" + (f", test={test_s}" if test_s else "")
            prompt += f'<attempt {score_str}>\n'
            prompt += f'Description: "{h["description"]}"\n'
            if "results" in h:
                prompt += "Train results:\n"
                for r in h["results"]:
                    status = "PASS" if r["pass"] else "FAIL"
                    prompt += f'  [{status}] "{r["query"][:80]}" (triggered {r["triggers"]}/{r["runs"]})\n'
            if h.get("note"):
                prompt += f'Note: {h["note"]}\n'
            prompt += "</attempt>\n\n"

    prompt += f"""</scores_summary>

Skill content (for context on what the skill does):
<skill_content>
{skill_content}
</skill_content>

Based on the failures, write a new and improved description that is more likely to trigger correctly. When I say "based on the failures", it's a bit of a tricky line to walk because we don't want to overfit to the specific cases you're seeing. So what I DON'T want you to do is produce an ever-expanding list of specific queries that this skill should or shouldn't trigger for. Instead, try to generalize from the failures to broader categories of user intent and situations where this skill would be useful or not useful. The reason for this is twofold:

1. Avoid overfitting
2. The list might get loooong and it's injected into ALL queries and there might be a lot of skills, so we don't want to blow too much space on any given description.

Concretely, your description should not be more than about 100-200 words, even if that comes at the cost of accuracy. There is a hard limit of 1024 characters — descriptions over that will be truncated, so stay comfortably under it.

Here are some tips that we've found to work well in writing these descriptions:
- The skill should be phrased in the imperative -- "Use this skill for" rather than "this skill does"
- The skill description should focus on the user's intent, what they are trying to achieve, vs. the implementation details of how the skill works.
- The description competes with other skills for Claude's attention — make it distinctive and immediately recognizable.
- If you're getting lots of failures after repeated attempts, change things up. Try different sentence structures or wordings.

I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end. 

Please respond with only the new description text in <new_description> tags, nothing else."""

    text = _call_claude(prompt, model)

    match = re.search(r"<new_description>(.*?)</new_description>", text, re.DOTALL)
    description = match.group(1).strip().strip('"') if match else text.strip().strip('"')

    transcript: dict = {
        "iteration": iteration,
        "prompt": prompt,
        "response": text,
        "parsed_description": description,
        "char_count": len(description),
        "over_limit": len(description) > 1024,
    }

    # Safety net: the prompt already states the 1024-char hard limit, but if
    # the model blew past it anyway, make one fresh single-turn call that
    # quotes the too-long version and asks for a shorter rewrite. (The old
    # SDK path did this as a true multi-turn; `claude -p` is one-shot, so we
    # inline the prior output into the new prompt instead.)
    if len(description) > 1024:
        shorten_prompt = (
            f"{prompt}\n\n"
            f"---\n\n"
            f"A previous attempt produced this description, which at "
            f"{len(description)} characters is over the 1024-character hard limit:\n\n"
            f'"{description}"\n\n'
            f"Rewrite it to be under 1024 characters while keeping the most "
            f"important trigger words and intent coverage. Respond with only "
            f"the new description in <new_description> tags."
        )
        shorten_text = _call_claude(shorten_prompt, model)
        match = re.search(r"<new_description>(.*?)</new_description>", shorten_text, re.DOTALL)
        shortened = match.group(1).strip().strip('"') if match else shorten_text.strip().strip('"')

        transcript["rewrite_prompt"] = shorten_prompt
        transcript["rewrite_response"] = shorten_text
        transcript["rewrite_description"] = shortened
        transcript["rewrite_char_count"] = len(shortened)
        description = shortened

    transcript["final_description"] = description

    if log_dir:
        log_dir.mkdir(parents=True, exist_ok=True)
        log_file = log_dir / f"improve_iter_{iteration or 'unknown'}.json"
        log_file.write_text(json.dumps(transcript, indent=2))

    return description


def main():
    parser = argparse.ArgumentParser(description="Improve a skill description based on eval results")
    parser.add_argument("--eval-results", required=True, help="Path to eval results JSON (from run_eval.py)")
    parser.add_argument("--skill-path", required=True, help="Path to skill directory")
    parser.add_argument("--history", default=None, help="Path to history JSON (previous attempts)")
    parser.add_argument("--model", required=True, help="Model for improvement")
    parser.add_argument("--verbose", action="store_true", help="Print thinking to stderr")
    args = parser.parse_args()

    skill_path = Path(args.skill_path)
    if not (skill_path / "SKILL.md").exists():
        print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
        sys.exit(1)

    eval_results = json.loads(Path(args.eval_results).read_text())
    history = []
    if args.history:
        history = json.loads(Path(args.history).read_text())

    name, _, content = parse_skill_md(skill_path)
    current_description = eval_results["description"]

    if args.verbose:
        print(f"Current: {current_description}", file=sys.stderr)
        print(f"Score: {eval_results['summary']['passed']}/{eval_results['summary']['total']}", file=sys.stderr)

    new_description = improve_description(
        skill_name=name,
        skill_content=content,
        current_description=current_description,
        eval_results=eval_results,
        history=history,
        model=args.model,
    )

    if args.verbose:
        print(f"Improved: {new_description}", file=sys.stderr)

    # Output as JSON with both the new description and updated history
    output = {
        "description": new_description,
        "history": history + [{
            "description": current_description,
            "passed": eval_results["summary"]["passed"],
            "failed": eval_results["summary"]["failed"],
            "total": eval_results["summary"]["total"],
            "results": eval_results["results"],
        }],
    }
    print(json.dumps(output, indent=2))


if __name__ == "__main__":
    main()

FILE:scripts/aggregate_benchmark.py
#!/usr/bin/env python3
"""
Aggregate individual run results into benchmark summary statistics.

Reads grading.json files from run directories and produces:
- run_summary with mean, stddev, min, max for each metric
- delta between with_skill and without_skill configurations

Usage:
    python aggregate_benchmark.py <benchmark_dir>

Example:
    python aggregate_benchmark.py benchmarks/2026-01-15T10-30-00/

The script supports two directory layouts:

    Workspace layout (from skill-creator iterations):
    <benchmark_dir>/
    └── eval-N/
        ├── with_skill/
        │   ├── run-1/grading.json
        │   └── run-2/grading.json
        └── without_skill/
            ├── run-1/grading.json
            └── run-2/grading.json

    Legacy layout (with runs/ subdirectory):
    <benchmark_dir>/
    └── runs/
        └── eval-N/
            ├── with_skill/
            │   └── run-1/grading.json
            └── without_skill/
                └── run-1/grading.json
"""

import argparse
import json
import math
import sys
from datetime import datetime, timezone
from pathlib import Path


def calculate_stats(values: list[float]) -> dict:
    """Calculate mean, stddev, min, max for a list of values."""
    if not values:
        return {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0}

    n = len(values)
    mean = sum(values) / n

    if n > 1:
        variance = sum((x - mean) ** 2 for x in values) / (n - 1)
        stddev = math.sqrt(variance)
    else:
        stddev = 0.0

    return {
        "mean": round(mean, 4),
        "stddev": round(stddev, 4),
        "min": round(min(values), 4),
        "max": round(max(values), 4)
    }


def load_run_results(benchmark_dir: Path) -> dict:
    """
    Load all run results from a benchmark directory.

    Returns dict keyed by config name (e.g. "with_skill"/"without_skill",
    or "new_skill"/"old_skill"), each containing a list of run results.
    """
    # Support both layouts: eval dirs directly under benchmark_dir, or under runs/
    runs_dir = benchmark_dir / "runs"
    if runs_dir.exists():
        search_dir = runs_dir
    elif list(benchmark_dir.glob("eval-*")):
        search_dir = benchmark_dir
    else:
        print(f"No eval directories found in {benchmark_dir} or {benchmark_dir / 'runs'}")
        return {}

    results: dict[str, list] = {}

    for eval_idx, eval_dir in enumerate(sorted(search_dir.glob("eval-*"))):
        metadata_path = eval_dir / "eval_metadata.json"
        if metadata_path.exists():
            try:
                with open(metadata_path) as mf:
                    eval_id = json.load(mf).get("eval_id", eval_idx)
            except (json.JSONDecodeError, OSError):
                eval_id = eval_idx
        else:
            try:
                eval_id = int(eval_dir.name.split("-")[1])
            except ValueError:
                eval_id = eval_idx

        # Discover config directories dynamically rather than hardcoding names
        for config_dir in sorted(eval_dir.iterdir()):
            if not config_dir.is_dir():
                continue
            # Skip non-config directories (inputs, outputs, etc.)
            if not list(config_dir.glob("run-*")):
                continue
            config = config_dir.name
            if config not in results:
                results[config] = []

            for run_dir in sorted(config_dir.glob("run-*")):
                run_number = int(run_dir.name.split("-")[1])
                grading_file = run_dir / "grading.json"

                if not grading_file.exists():
                    print(f"Warning: grading.json not found in {run_dir}")
                    continue

                try:
                    with open(grading_file) as f:
                        grading = json.load(f)
                except json.JSONDecodeError as e:
                    print(f"Warning: Invalid JSON in {grading_file}: {e}")
                    continue

                # Extract metrics
                result = {
                    "eval_id": eval_id,
                    "run_number": run_number,
                    "pass_rate": grading.get("summary", {}).get("pass_rate", 0.0),
                    "passed": grading.get("summary", {}).get("passed", 0),
                    "failed": grading.get("summary", {}).get("failed", 0),
                    "total": grading.get("summary", {}).get("total", 0),
                }

                # Extract timing — check grading.json first, then sibling timing.json
                timing = grading.get("timing", {})
                result["time_seconds"] = timing.get("total_duration_seconds", 0.0)
                timing_file = run_dir / "timing.json"
                if result["time_seconds"] == 0.0 and timing_file.exists():
                    try:
                        with open(timing_file) as tf:
                            timing_data = json.load(tf)
                        result["time_seconds"] = timing_data.get("total_duration_seconds", 0.0)
                        result["tokens"] = timing_data.get("total_tokens", 0)
                    except json.JSONDecodeError:
                        pass

                # Extract metrics if available
                metrics = grading.get("execution_metrics", {})
                result["tool_calls"] = metrics.get("total_tool_calls", 0)
                if not result.get("tokens"):
                    result["tokens"] = metrics.get("output_chars", 0)
                result["errors"] = metrics.get("errors_encountered", 0)

                # Extract expectations — viewer requires fields: text, passed, evidence
                raw_expectations = grading.get("expectations", [])
                for exp in raw_expectations:
                    if "text" not in exp or "passed" not in exp:
                        print(f"Warning: expectation in {grading_file} missing required fields (text, passed, evidence): {exp}")
                result["expectations"] = raw_expectations

                # Extract notes from user_notes_summary
                notes_summary = grading.get("user_notes_summary", {})
                notes = []
                notes.extend(notes_summary.get("uncertainties", []))
                notes.extend(notes_summary.get("needs_review", []))
                notes.extend(notes_summary.get("workarounds", []))
                result["notes"] = notes

                results[config].append(result)

    return results


def aggregate_results(results: dict) -> dict:
    """
    Aggregate run results into summary statistics.

    Returns run_summary with stats for each configuration and delta.
    """
    run_summary = {}
    configs = list(results.keys())

    for config in configs:
        runs = results.get(config, [])

        if not runs:
            run_summary[config] = {
                "pass_rate": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0},
                "time_seconds": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0},
                "tokens": {"mean": 0, "stddev": 0, "min": 0, "max": 0}
            }
            continue

        pass_rates = [r["pass_rate"] for r in runs]
        times = [r["time_seconds"] for r in runs]
        tokens = [r.get("tokens", 0) for r in runs]

        run_summary[config] = {
            "pass_rate": calculate_stats(pass_rates),
            "time_seconds": calculate_stats(times),
            "tokens": calculate_stats(tokens)
        }

    # Calculate delta between the first two configs (if two exist)
    if len(configs) >= 2:
        primary = run_summary.get(configs[0], {})
        baseline = run_summary.get(configs[1], {})
    else:
        primary = run_summary.get(configs[0], {}) if configs else {}
        baseline = {}

    delta_pass_rate = primary.get("pass_rate", {}).get("mean", 0) - baseline.get("pass_rate", {}).get("mean", 0)
    delta_time = primary.get("time_seconds", {}).get("mean", 0) - baseline.get("time_seconds", {}).get("mean", 0)
    delta_tokens = primary.get("tokens", {}).get("mean", 0) - baseline.get("tokens", {}).get("mean", 0)

    run_summary["delta"] = {
        "pass_rate": f"{delta_pass_rate:+.2f}",
        "time_seconds": f"{delta_time:+.1f}",
        "tokens": f"{delta_tokens:+.0f}"
    }

    return run_summary


def generate_benchmark(benchmark_dir: Path, skill_name: str = "", skill_path: str = "") -> dict:
    """
    Generate complete benchmark.json from run results.
    """
    results = load_run_results(benchmark_dir)
    run_summary = aggregate_results(results)

    # Build runs array for benchmark.json
    runs = []
    for config in results:
        for result in results[config]:
            runs.append({
                "eval_id": result["eval_id"],
                "configuration": config,
                "run_number": result["run_number"],
                "result": {
                    "pass_rate": result["pass_rate"],
                    "passed": result["passed"],
                    "failed": result["failed"],
                    "total": result["total"],
                    "time_seconds": result["time_seconds"],
                    "tokens": result.get("tokens", 0),
                    "tool_calls": result.get("tool_calls", 0),
                    "errors": result.get("errors", 0)
                },
                "expectations": result["expectations"],
                "notes": result["notes"]
            })

    # Determine eval IDs from results
    eval_ids = sorted(set(
        r["eval_id"]
        for config in results.values()
        for r in config
    ))

    benchmark = {
        "metadata": {
            "skill_name": skill_name or "<skill-name>",
            "skill_path": skill_path or "<path/to/skill>",
            "executor_model": "<model-name>",
            "analyzer_model": "<model-name>",
            "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
            "evals_run": eval_ids,
            "runs_per_configuration": 3
        },
        "runs": runs,
        "run_summary": run_summary,
        "notes": []  # To be filled by analyzer
    }

    return benchmark


def generate_markdown(benchmark: dict) -> str:
    """Generate human-readable benchmark.md from benchmark data."""
    metadata = benchmark["metadata"]
    run_summary = benchmark["run_summary"]

    # Determine config names (excluding "delta")
    configs = [k for k in run_summary if k != "delta"]
    config_a = configs[0] if len(configs) >= 1 else "config_a"
    config_b = configs[1] if len(configs) >= 2 else "config_b"
    label_a = config_a.replace("_", " ").title()
    label_b = config_b.replace("_", " ").title()

    lines = [
        f"# Skill Benchmark: {metadata['skill_name']}",
        "",
        f"**Model**: {metadata['executor_model']}",
        f"**Date**: {metadata['timestamp']}",
        f"**Evals**: {', '.join(map(str, metadata['evals_run']))} ({metadata['runs_per_configuration']} runs each per configuration)",
        "",
        "## Summary",
        "",
        f"| Metric | {label_a} | {label_b} | Delta |",
        "|--------|------------|---------------|-------|",
    ]

    a_summary = run_summary.get(config_a, {})
    b_summary = run_summary.get(config_b, {})
    delta = run_summary.get("delta", {})

    # Format pass rate
    a_pr = a_summary.get("pass_rate", {})
    b_pr = b_summary.get("pass_rate", {})
    lines.append(f"| Pass Rate | {a_pr.get('mean', 0)*100:.0f}% ± {a_pr.get('stddev', 0)*100:.0f}% | {b_pr.get('mean', 0)*100:.0f}% ± {b_pr.get('stddev', 0)*100:.0f}% | {delta.get('pass_rate', '—')} |")

    # Format time
    a_time = a_summary.get("time_seconds", {})
    b_time = b_summary.get("time_seconds", {})
    lines.append(f"| Time | {a_time.get('mean', 0):.1f}s ± {a_time.get('stddev', 0):.1f}s | {b_time.get('mean', 0):.1f}s ± {b_time.get('stddev', 0):.1f}s | {delta.get('time_seconds', '—')}s |")

    # Format tokens
    a_tokens = a_summary.get("tokens", {})
    b_tokens = b_summary.get("tokens", {})
    lines.append(f"| Tokens | {a_tokens.get('mean', 0):.0f} ± {a_tokens.get('stddev', 0):.0f} | {b_tokens.get('mean', 0):.0f} ± {b_tokens.get('stddev', 0):.0f} | {delta.get('tokens', '—')} |")

    # Notes section
    if benchmark.get("notes"):
        lines.extend([
            "",
            "## Notes",
            ""
        ])
        for note in benchmark["notes"]:
            lines.append(f"- {note}")

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Aggregate benchmark run results into summary statistics"
    )
    parser.add_argument(
        "benchmark_dir",
        type=Path,
        help="Path to the benchmark directory"
    )
    parser.add_argument(
        "--skill-name",
        default="",
        help="Name of the skill being benchmarked"
    )
    parser.add_argument(
        "--skill-path",
        default="",
        help="Path to the skill being benchmarked"
    )
    parser.add_argument(
        "--output", "-o",
        type=Path,
        help="Output path for benchmark.json (default: <benchmark_dir>/benchmark.json)"
    )

    args = parser.parse_args()

    if not args.benchmark_dir.exists():
        print(f"Directory not found: {args.benchmark_dir}")
        sys.exit(1)

    # Generate benchmark
    benchmark = generate_benchmark(args.benchmark_dir, args.skill_name, args.skill_path)

    # Determine output paths
    output_json = args.output or (args.benchmark_dir / "benchmark.json")
    output_md = output_json.with_suffix(".md")

    # Write benchmark.json
    with open(output_json, "w") as f:
        json.dump(benchmark, f, indent=2)
    print(f"Generated: {output_json}")

    # Write benchmark.md
    markdown = generate_markdown(benchmark)
    with open(output_md, "w") as f:
        f.write(markdown)
    print(f"Generated: {output_md}")

    # Print summary
    run_summary = benchmark["run_summary"]
    configs = [k for k in run_summary if k != "delta"]
    delta = run_summary.get("delta", {})

    print(f"\nSummary:")
    for config in configs:
        pr = run_summary[config]["pass_rate"]["mean"]
        label = config.replace("_", " ").title()
        print(f"  {label}: {pr*100:.1f}% pass rate")
    print(f"  Delta:         {delta.get('pass_rate', '—')}")


if __name__ == "__main__":
    main()

FILE:scripts/__init__.py

FILE:scripts/run_loop.py
#!/usr/bin/env python3
"""Run the eval + improve loop until all pass or max iterations reached.

Combines run_eval.py and improve_description.py in a loop, tracking history
and returning the best description found. Supports train/test split to prevent
overfitting.
"""

import argparse
import json
import random
import sys
import tempfile
import time
import webbrowser
from pathlib import Path

from scripts.generate_report import generate_html
from scripts.improve_description import improve_description
from scripts.run_eval import find_project_root, run_eval
from scripts.utils import parse_skill_md


def split_eval_set(eval_set: list[dict], holdout: float, seed: int = 42) -> tuple[list[dict], list[dict]]:
    """Split eval set into train and test sets, stratified by should_trigger."""
    random.seed(seed)

    # Separate by should_trigger
    trigger = [e for e in eval_set if e["should_trigger"]]
    no_trigger = [e for e in eval_set if not e["should_trigger"]]

    # Shuffle each group
    random.shuffle(trigger)
    random.shuffle(no_trigger)

    # Calculate split points
    n_trigger_test = max(1, int(len(trigger) * holdout))
    n_no_trigger_test = max(1, int(len(no_trigger) * holdout))

    # Split
    test_set = trigger[:n_trigger_test] + no_trigger[:n_no_trigger_test]
    train_set = trigger[n_trigger_test:] + no_trigger[n_no_trigger_test:]

    return train_set, test_set


def run_loop(
    eval_set: list[dict],
    skill_path: Path,
    description_override: str | None,
    num_workers: int,
    timeout: int,
    max_iterations: int,
    runs_per_query: int,
    trigger_threshold: float,
    holdout: float,
    model: str,
    verbose: bool,
    live_report_path: Path | None = None,
    log_dir: Path | None = None,
) -> dict:
    """Run the eval + improvement loop."""
    project_root = find_project_root()
    name, original_description, content = parse_skill_md(skill_path)
    current_description = description_override or original_description

    # Split into train/test if holdout > 0
    if holdout > 0:
        train_set, test_set = split_eval_set(eval_set, holdout)
        if verbose:
            print(f"Split: {len(train_set)} train, {len(test_set)} test (holdout={holdout})", file=sys.stderr)
    else:
        train_set = eval_set
        test_set = []

    history = []
    exit_reason = "unknown"

    for iteration in range(1, max_iterations + 1):
        if verbose:
            print(f"\n{'='*60}", file=sys.stderr)
            print(f"Iteration {iteration}/{max_iterations}", file=sys.stderr)
            print(f"Description: {current_description}", file=sys.stderr)
            print(f"{'='*60}", file=sys.stderr)

        # Evaluate train + test together in one batch for parallelism
        all_queries = train_set + test_set
        t0 = time.time()
        all_results = run_eval(
            eval_set=all_queries,
            skill_name=name,
            description=current_description,
            num_workers=num_workers,
            timeout=timeout,
            project_root=project_root,
            runs_per_query=runs_per_query,
            trigger_threshold=trigger_threshold,
            model=model,
        )
        eval_elapsed = time.time() - t0

        # Split results back into train/test by matching queries
        train_queries_set = {q["query"] for q in train_set}
        train_result_list = [r for r in all_results["results"] if r["query"] in train_queries_set]
        test_result_list = [r for r in all_results["results"] if r["query"] not in train_queries_set]

        train_passed = sum(1 for r in train_result_list if r["pass"])
        train_total = len(train_result_list)
        train_summary = {"passed": train_passed, "failed": train_total - train_passed, "total": train_total}
        train_results = {"results": train_result_list, "summary": train_summary}

        if test_set:
            test_passed = sum(1 for r in test_result_list if r["pass"])
            test_total = len(test_result_list)
            test_summary = {"passed": test_passed, "failed": test_total - test_passed, "total": test_total}
            test_results = {"results": test_result_list, "summary": test_summary}
        else:
            test_results = None
            test_summary = None

        history.append({
            "iteration": iteration,
            "description": current_description,
            "train_passed": train_summary["passed"],
            "train_failed": train_summary["failed"],
            "train_total": train_summary["total"],
            "train_results": train_results["results"],
            "test_passed": test_summary["passed"] if test_summary else None,
            "test_failed": test_summary["failed"] if test_summary else None,
            "test_total": test_summary["total"] if test_summary else None,
            "test_results": test_results["results"] if test_results else None,
            # For backward compat with report generator
            "passed": train_summary["passed"],
            "failed": train_summary["failed"],
            "total": train_summary["total"],
            "results": train_results["results"],
        })

        # Write live report if path provided
        if live_report_path:
            partial_output = {
                "original_description": original_description,
                "best_description": current_description,
                "best_score": "in progress",
                "iterations_run": len(history),
                "holdout": holdout,
                "train_size": len(train_set),
                "test_size": len(test_set),
                "history": history,
            }
            live_report_path.write_text(generate_html(partial_output, auto_refresh=True, skill_name=name))

        if verbose:
            def print_eval_stats(label, results, elapsed):
                pos = [r for r in results if r["should_trigger"]]
                neg = [r for r in results if not r["should_trigger"]]
                tp = sum(r["triggers"] for r in pos)
                pos_runs = sum(r["runs"] for r in pos)
                fn = pos_runs - tp
                fp = sum(r["triggers"] for r in neg)
                neg_runs = sum(r["runs"] for r in neg)
                tn = neg_runs - fp
                total = tp + tn + fp + fn
                precision = tp / (tp + fp) if (tp + fp) > 0 else 1.0
                recall = tp / (tp + fn) if (tp + fn) > 0 else 1.0
                accuracy = (tp + tn) / total if total > 0 else 0.0
                print(f"{label}: {tp+tn}/{total} correct, precision={precision:.0%} recall={recall:.0%} accuracy={accuracy:.0%} ({elapsed:.1f}s)", file=sys.stderr)
                for r in results:
                    status = "PASS" if r["pass"] else "FAIL"
                    rate_str = f"{r['triggers']}/{r['runs']}"
                    print(f"  [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:60]}", file=sys.stderr)

            print_eval_stats("Train", train_results["results"], eval_elapsed)
            if test_summary:
                print_eval_stats("Test ", test_results["results"], 0)

        if train_summary["failed"] == 0:
            exit_reason = f"all_passed (iteration {iteration})"
            if verbose:
                print(f"\nAll train queries passed on iteration {iteration}!", file=sys.stderr)
            break

        if iteration == max_iterations:
            exit_reason = f"max_iterations ({max_iterations})"
            if verbose:
                print(f"\nMax iterations reached ({max_iterations}).", file=sys.stderr)
            break

        # Improve the description based on train results
        if verbose:
            print(f"\nImproving description...", file=sys.stderr)

        t0 = time.time()
        # Strip test scores from history so improvement model can't see them
        blinded_history = [
            {k: v for k, v in h.items() if not k.startswith("test_")}
            for h in history
        ]
        new_description = improve_description(
            skill_name=name,
            skill_content=content,
            current_description=current_description,
            eval_results=train_results,
            history=blinded_history,
            model=model,
            log_dir=log_dir,
            iteration=iteration,
        )
        improve_elapsed = time.time() - t0

        if verbose:
            print(f"Proposed ({improve_elapsed:.1f}s): {new_description}", file=sys.stderr)

        current_description = new_description

    # Find the best iteration by TEST score (or train if no test set)
    if test_set:
        best = max(history, key=lambda h: h["test_passed"] or 0)
        best_score = f"{best['test_passed']}/{best['test_total']}"
    else:
        best = max(history, key=lambda h: h["train_passed"])
        best_score = f"{best['train_passed']}/{best['train_total']}"

    if verbose:
        print(f"\nExit reason: {exit_reason}", file=sys.stderr)
        print(f"Best score: {best_score} (iteration {best['iteration']})", file=sys.stderr)

    return {
        "exit_reason": exit_reason,
        "original_description": original_description,
        "best_description": best["description"],
        "best_score": best_score,
        "best_train_score": f"{best['train_passed']}/{best['train_total']}",
        "best_test_score": f"{best['test_passed']}/{best['test_total']}" if test_set else None,
        "final_description": current_description,
        "iterations_run": len(history),
        "holdout": holdout,
        "train_size": len(train_set),
        "test_size": len(test_set),
        "history": history,
    }


def main():
    parser = argparse.ArgumentParser(description="Run eval + improve loop")
    parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
    parser.add_argument("--skill-path", required=True, help="Path to skill directory")
    parser.add_argument("--description", default=None, help="Override starting description")
    parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
    parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
    parser.add_argument("--max-iterations", type=int, default=5, help="Max improvement iterations")
    parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
    parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
    parser.add_argument("--holdout", type=float, default=0.4, help="Fraction of eval set to hold out for testing (0 to disable)")
    parser.add_argument("--model", required=True, help="Model for improvement")
    parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
    parser.add_argument("--report", default="auto", help="Generate HTML report at this path (default: 'auto' for temp file, 'none' to disable)")
    parser.add_argument("--results-dir", default=None, help="Save all outputs (results.json, report.html, log.txt) to a timestamped subdirectory here")
    args = parser.parse_args()

    eval_set = json.loads(Path(args.eval_set).read_text())
    skill_path = Path(args.skill_path)

    if not (skill_path / "SKILL.md").exists():
        print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
        sys.exit(1)

    name, _, _ = parse_skill_md(skill_path)

    # Set up live report path
    if args.report != "none":
        if args.report == "auto":
            timestamp = time.strftime("%Y%m%d_%H%M%S")
            live_report_path = Path(tempfile.gettempdir()) / f"skill_description_report_{skill_path.name}_{timestamp}.html"
        else:
            live_report_path = Path(args.report)
        # Open the report immediately so the user can watch
        live_report_path.write_text("<html><body><h1>Starting optimization loop...</h1><meta http-equiv='refresh' content='5'></body></html>")
        webbrowser.open(str(live_report_path))
    else:
        live_report_path = None

    # Determine output directory (create before run_loop so logs can be written)
    if args.results_dir:
        timestamp = time.strftime("%Y-%m-%d_%H%M%S")
        results_dir = Path(args.results_dir) / timestamp
        results_dir.mkdir(parents=True, exist_ok=True)
    else:
        results_dir = None

    log_dir = results_dir / "logs" if results_dir else None

    output = run_loop(
        eval_set=eval_set,
        skill_path=skill_path,
        description_override=args.description,
        num_workers=args.num_workers,
        timeout=args.timeout,
        max_iterations=args.max_iterations,
        runs_per_query=args.runs_per_query,
        trigger_threshold=args.trigger_threshold,
        holdout=args.holdout,
        model=args.model,
        verbose=args.verbose,
        live_report_path=live_report_path,
        log_dir=log_dir,
    )

    # Save JSON output
    json_output = json.dumps(output, indent=2)
    print(json_output)
    if results_dir:
        (results_dir / "results.json").write_text(json_output)

    # Write final HTML report (without auto-refresh)
    if live_report_path:
        live_report_path.write_text(generate_html(output, auto_refresh=False, skill_name=name))
        print(f"\nReport: {live_report_path}", file=sys.stderr)

    if results_dir and live_report_path:
        (results_dir / "report.html").write_text(generate_html(output, auto_refresh=False, skill_name=name))

    if results_dir:
        print(f"Results saved to: {results_dir}", file=sys.stderr)


if __name__ == "__main__":
    main()

FILE:scripts/generate_report.py
#!/usr/bin/env python3
"""Generate an HTML report from run_loop.py output.

Takes the JSON output from run_loop.py and generates a visual HTML report
showing each description attempt with check/x for each test case.
Distinguishes between train and test queries.
"""

import argparse
import html
import json
import sys
from pathlib import Path


def generate_html(data: dict, auto_refresh: bool = False, skill_name: str = "") -> str:
    """Generate HTML report from loop output data. If auto_refresh is True, adds a meta refresh tag."""
    history = data.get("history", [])
    holdout = data.get("holdout", 0)
    title_prefix = html.escape(skill_name + " \u2014 ") if skill_name else ""

    # Get all unique queries from train and test sets, with should_trigger info
    train_queries: list[dict] = []
    test_queries: list[dict] = []
    if history:
        for r in history[0].get("train_results", history[0].get("results", [])):
            train_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)})
        if history[0].get("test_results"):
            for r in history[0].get("test_results", []):
                test_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)})

    refresh_tag = '    <meta http-equiv="refresh" content="5">\n' if auto_refresh else ""

    html_parts = ["""<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
""" + refresh_tag + """    <title>""" + title_prefix + """Skill Description Optimization</title>
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
    <style>
        body {
            font-family: 'Lora', Georgia, serif;
            max-width: 100%;
            margin: 0 auto;
            padding: 20px;
            background: #faf9f5;
            color: #141413;
        }
        h1 { font-family: 'Poppins', sans-serif; color: #141413; }
        .explainer {
            background: white;
            padding: 15px;
            border-radius: 6px;
            margin-bottom: 20px;
            border: 1px solid #e8e6dc;
            color: #b0aea5;
            font-size: 0.875rem;
            line-height: 1.6;
        }
        .summary {
            background: white;
            padding: 15px;
            border-radius: 6px;
            margin-bottom: 20px;
            border: 1px solid #e8e6dc;
        }
        .summary p { margin: 5px 0; }
        .best { color: #788c5d; font-weight: bold; }
        .table-container {
            overflow-x: auto;
            width: 100%;
        }
        table {
            border-collapse: collapse;
            background: white;
            border: 1px solid #e8e6dc;
            border-radius: 6px;
            font-size: 12px;
            min-width: 100%;
        }
        th, td {
            padding: 8px;
            text-align: left;
            border: 1px solid #e8e6dc;
            white-space: normal;
            word-wrap: break-word;
        }
        th {
            font-family: 'Poppins', sans-serif;
            background: #141413;
            color: #faf9f5;
            font-weight: 500;
        }
        th.test-col {
            background: #6a9bcc;
        }
        th.query-col { min-width: 200px; }
        td.description {
            font-family: monospace;
            font-size: 11px;
            word-wrap: break-word;
            max-width: 400px;
        }
        td.result {
            text-align: center;
            font-size: 16px;
            min-width: 40px;
        }
        td.test-result {
            background: #f0f6fc;
        }
        .pass { color: #788c5d; }
        .fail { color: #c44; }
        .rate {
            font-size: 9px;
            color: #b0aea5;
            display: block;
        }
        tr:hover { background: #faf9f5; }
        .score {
            display: inline-block;
            padding: 2px 6px;
            border-radius: 4px;
            font-weight: bold;
            font-size: 11px;
        }
        .score-good { background: #eef2e8; color: #788c5d; }
        .score-ok { background: #fef3c7; color: #d97706; }
        .score-bad { background: #fceaea; color: #c44; }
        .train-label { color: #b0aea5; font-size: 10px; }
        .test-label { color: #6a9bcc; font-size: 10px; font-weight: bold; }
        .best-row { background: #f5f8f2; }
        th.positive-col { border-bottom: 3px solid #788c5d; }
        th.negative-col { border-bottom: 3px solid #c44; }
        th.test-col.positive-col { border-bottom: 3px solid #788c5d; }
        th.test-col.negative-col { border-bottom: 3px solid #c44; }
        .legend { font-family: 'Poppins', sans-serif; display: flex; gap: 20px; margin-bottom: 10px; font-size: 13px; align-items: center; }
        .legend-item { display: flex; align-items: center; gap: 6px; }
        .legend-swatch { width: 16px; height: 16px; border-radius: 3px; display: inline-block; }
        .swatch-positive { background: #141413; border-bottom: 3px solid #788c5d; }
        .swatch-negative { background: #141413; border-bottom: 3px solid #c44; }
        .swatch-test { background: #6a9bcc; }
        .swatch-train { background: #141413; }
    </style>
</head>
<body>
    <h1>""" + title_prefix + """Skill Description Optimization</h1>
    <div class="explainer">
        <strong>Optimizing your skill's description.</strong> This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, Claude will apply the best-performing description to your skill.
    </div>
"""]

    # Summary section
    best_test_score = data.get('best_test_score')
    best_train_score = data.get('best_train_score')
    html_parts.append(f"""
    <div class="summary">
        <p><strong>Original:</strong> {html.escape(data.get('original_description', 'N/A'))}</p>
        <p class="best"><strong>Best:</strong> {html.escape(data.get('best_description', 'N/A'))}</p>
        <p><strong>Best Score:</strong> {data.get('best_score', 'N/A')} {'(test)' if best_test_score else '(train)'}</p>
        <p><strong>Iterations:</strong> {data.get('iterations_run', 0)} | <strong>Train:</strong> {data.get('train_size', '?')} | <strong>Test:</strong> {data.get('test_size', '?')}</p>
    </div>
""")

    # Legend
    html_parts.append("""
    <div class="legend">
        <span style="font-weight:600">Query columns:</span>
        <span class="legend-item"><span class="legend-swatch swatch-positive"></span> Should trigger</span>
        <span class="legend-item"><span class="legend-swatch swatch-negative"></span> Should NOT trigger</span>
        <span class="legend-item"><span class="legend-swatch swatch-train"></span> Train</span>
        <span class="legend-item"><span class="legend-swatch swatch-test"></span> Test</span>
    </div>
""")

    # Table header
    html_parts.append("""
    <div class="table-container">
    <table>
        <thead>
            <tr>
                <th>Iter</th>
                <th>Train</th>
                <th>Test</th>
                <th class="query-col">Description</th>
""")

    # Add column headers for train queries
    for qinfo in train_queries:
        polarity = "positive-col" if qinfo["should_trigger"] else "negative-col"
        html_parts.append(f'                <th class="{polarity}">{html.escape(qinfo["query"])}</th>\n')

    # Add column headers for test queries (different color)
    for qinfo in test_queries:
        polarity = "positive-col" if qinfo["should_trigger"] else "negative-col"
        html_parts.append(f'                <th class="test-col {polarity}">{html.escape(qinfo["query"])}</th>\n')

    html_parts.append("""            </tr>
        </thead>
        <tbody>
""")

    # Find best iteration for highlighting
    if test_queries:
        best_iter = max(history, key=lambda h: h.get("test_passed") or 0).get("iteration")
    else:
        best_iter = max(history, key=lambda h: h.get("train_passed", h.get("passed", 0))).get("iteration")

    # Add rows for each iteration
    for h in history:
        iteration = h.get("iteration", "?")
        train_passed = h.get("train_passed", h.get("passed", 0))
        train_total = h.get("train_total", h.get("total", 0))
        test_passed = h.get("test_passed")
        test_total = h.get("test_total")
        description = h.get("description", "")
        train_results = h.get("train_results", h.get("results", []))
        test_results = h.get("test_results", [])

        # Create lookups for results by query
        train_by_query = {r["query"]: r for r in train_results}
        test_by_query = {r["query"]: r for r in test_results} if test_results else {}

        # Compute aggregate correct/total runs across all retries
        def aggregate_runs(results: list[dict]) -> tuple[int, int]:
            correct = 0
            total = 0
            for r in results:
                runs = r.get("runs", 0)
                triggers = r.get("triggers", 0)
                total += runs
                if r.get("should_trigger", True):
                    correct += triggers
                else:
                    correct += runs - triggers
            return correct, total

        train_correct, train_runs = aggregate_runs(train_results)
        test_correct, test_runs = aggregate_runs(test_results)

        # Determine score classes
        def score_class(correct: int, total: int) -> str:
            if total > 0:
                ratio = correct / total
                if ratio >= 0.8:
                    return "score-good"
                elif ratio >= 0.5:
                    return "score-ok"
            return "score-bad"

        train_class = score_class(train_correct, train_runs)
        test_class = score_class(test_correct, test_runs)

        row_class = "best-row" if iteration == best_iter else ""

        html_parts.append(f"""            <tr class="{row_class}">
                <td>{iteration}</td>
                <td><span class="score {train_class}">{train_correct}/{train_runs}</span></td>
                <td><span class="score {test_class}">{test_correct}/{test_runs}</span></td>
                <td class="description">{html.escape(description)}</td>
""")

        # Add result for each train query
        for qinfo in train_queries:
            r = train_by_query.get(qinfo["query"], {})
            did_pass = r.get("pass", False)
            triggers = r.get("triggers", 0)
            runs = r.get("runs", 0)

            icon = "✓" if did_pass else "✗"
            css_class = "pass" if did_pass else "fail"

            html_parts.append(f'                <td class="result {css_class}">{icon}<span class="rate">{triggers}/{runs}</span></td>\n')

        # Add result for each test query (with different background)
        for qinfo in test_queries:
            r = test_by_query.get(qinfo["query"], {})
            did_pass = r.get("pass", False)
            triggers = r.get("triggers", 0)
            runs = r.get("runs", 0)

            icon = "✓" if did_pass else "✗"
            css_class = "pass" if did_pass else "fail"

            html_parts.append(f'                <td class="result test-result {css_class}">{icon}<span class="rate">{triggers}/{runs}</span></td>\n')

        html_parts.append("            </tr>\n")

    html_parts.append("""        </tbody>
    </table>
    </div>
""")

    html_parts.append("""
</body>
</html>
""")

    return "".join(html_parts)


def main():
    parser = argparse.ArgumentParser(description="Generate HTML report from run_loop output")
    parser.add_argument("input", help="Path to JSON output from run_loop.py (or - for stdin)")
    parser.add_argument("-o", "--output", default=None, help="Output HTML file (default: stdout)")
    parser.add_argument("--skill-name", default="", help="Skill name to include in the report title")
    args = parser.parse_args()

    if args.input == "-":
        data = json.load(sys.stdin)
    else:
        data = json.loads(Path(args.input).read_text())

    html_output = generate_html(data, skill_name=args.skill_name)

    if args.output:
        Path(args.output).write_text(html_output)
        print(f"Report written to {args.output}", file=sys.stderr)
    else:
        print(html_output)


if __name__ == "__main__":
    main()

FILE:scripts/utils.py
"""Shared utilities for skill-creator scripts."""

from pathlib import Path



def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
    """Parse a SKILL.md file, returning (name, description, full_content)."""
    content = (skill_path / "SKILL.md").read_text()
    lines = content.split("\n")

    if lines[0].strip() != "---":
        raise ValueError("SKILL.md missing frontmatter (no opening ---)")

    end_idx = None
    for i, line in enumerate(lines[1:], start=1):
        if line.strip() == "---":
            end_idx = i
            break

    if end_idx is None:
        raise ValueError("SKILL.md missing frontmatter (no closing ---)")

    name = ""
    description = ""
    frontmatter_lines = lines[1:end_idx]
    i = 0
    while i < len(frontmatter_lines):
        line = frontmatter_lines[i]
        if line.startswith("name:"):
            name = line[len("name:"):].strip().strip('"').strip("'")
        elif line.startswith("description:"):
            value = line[len("description:"):].strip()
            # Handle YAML multiline indicators (>, |, >-, |-)
            if value in (">", "|", ">-", "|-"):
                continuation_lines: list[str] = []
                i += 1
                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
                    continuation_lines.append(frontmatter_lines[i].strip())
                    i += 1
                description = " ".join(continuation_lines)
                continue
            else:
                description = value.strip('"').strip("'")
        i += 1

    return name, description, content

FILE:agents/grader.md
# Grader Agent

Evaluate expectations against an execution transcript and outputs.

## Role

The Grader reviews a transcript and output files, then determines whether each expectation passes or fails. Provide clear evidence for each judgment.

You have two jobs: grade the outputs, and critique the evals themselves. A passing grade on a weak assertion is worse than useless — it creates false confidence. When you notice an assertion that's trivially satisfied, or an important outcome that no assertion checks, say so.

## Inputs

You receive these parameters in your prompt:

- **expectations**: List of expectations to evaluate (strings)
- **transcript_path**: Path to the execution transcript (markdown file)
- **outputs_dir**: Directory containing output files from execution

## Process

### Step 1: Read the Transcript

1. Read the transcript file completely
2. Note the eval prompt, execution steps, and final result
3. Identify any issues or errors documented

### Step 2: Examine Output Files

1. List files in outputs_dir
2. Read/examine each file relevant to the expectations. If outputs aren't plain text, use the inspection tools provided in your prompt — don't rely solely on what the transcript says the executor produced.
3. Note contents, structure, and quality

### Step 3: Evaluate Each Assertion

For each expectation:

1. **Search for evidence** in the transcript and outputs
2. **Determine verdict**:
   - **PASS**: Clear evidence the expectation is true AND the evidence reflects genuine task completion, not just surface-level compliance
   - **FAIL**: No evidence, or evidence contradicts the expectation, or the evidence is superficial (e.g., correct filename but empty/wrong content)
3. **Cite the evidence**: Quote the specific text or describe what you found

### Step 4: Extract and Verify Claims

Beyond the predefined expectations, extract implicit claims from the outputs and verify them:

1. **Extract claims** from the transcript and outputs:
   - Factual statements ("The form has 12 fields")
   - Process claims ("Used pypdf to fill the form")
   - Quality claims ("All fields were filled correctly")

2. **Verify each claim**:
   - **Factual claims**: Can be checked against the outputs or external sources
   - **Process claims**: Can be verified from the transcript
   - **Quality claims**: Evaluate whether the claim is justified

3. **Flag unverifiable claims**: Note claims that cannot be verified with available information

This catches issues that predefined expectations might miss.

### Step 5: Read User Notes

If `{outputs_dir}/user_notes.md` exists:
1. Read it and note any uncertainties or issues flagged by the executor
2. Include relevant concerns in the grading output
3. These may reveal problems even when expectations pass

### Step 6: Critique the Evals

After grading, consider whether the evals themselves could be improved. Only surface suggestions when there's a clear gap.

Good suggestions test meaningful outcomes — assertions that are hard to satisfy without actually doing the work correctly. Think about what makes an assertion *discriminating*: it passes when the skill genuinely succeeds and fails when it doesn't.

Suggestions worth raising:
- An assertion that passed but would also pass for a clearly wrong output (e.g., checking filename existence but not file content)
- An important outcome you observed — good or bad — that no assertion covers at all
- An assertion that can't actually be verified from the available outputs

Keep the bar high. The goal is to flag things the eval author would say "good catch" about, not to nitpick every assertion.

### Step 7: Write Grading Results

Save results to `{outputs_dir}/../grading.json` (sibling to outputs_dir).

## Grading Criteria

**PASS when**:
- The transcript or outputs clearly demonstrate the expectation is true
- Specific evidence can be cited
- The evidence reflects genuine substance, not just surface compliance (e.g., a file exists AND contains correct content, not just the right filename)

**FAIL when**:
- No evidence found for the expectation
- Evidence contradicts the expectation
- The expectation cannot be verified from available information
- The evidence is superficial — the assertion is technically satisfied but the underlying task outcome is wrong or incomplete
- The output appears to meet the assertion by coincidence rather than by actually doing the work

**When uncertain**: The burden of proof to pass is on the expectation.

### Step 8: Read Executor Metrics and Timing

1. If `{outputs_dir}/metrics.json` exists, read it and include in grading output
2. If `{outputs_dir}/../timing.json` exists, read it and include timing data

## Output Format

Write a JSON file with this structure:

```json
{
  "expectations": [
    {
      "text": "The output includes the name 'John Smith'",
      "passed": true,
      "evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'"
    },
    {
      "text": "The spreadsheet has a SUM formula in cell B10",
      "passed": false,
      "evidence": "No spreadsheet was created. The output was a text file."
    },
    {
      "text": "The assistant used the skill's OCR script",
      "passed": true,
      "evidence": "Transcript Step 2 shows: 'Tool: Bash - python ocr_script.py image.png'"
    }
  ],
  "summary": {
    "passed": 2,
    "failed": 1,
    "total": 3,
    "pass_rate": 0.67
  },
  "execution_metrics": {
    "tool_calls": {
      "Read": 5,
      "Write": 2,
      "Bash": 8
    },
    "total_tool_calls": 15,
    "total_steps": 6,
    "errors_encountered": 0,
    "output_chars": 12450,
    "transcript_chars": 3200
  },
  "timing": {
    "executor_duration_seconds": 165.0,
    "grader_duration_seconds": 26.0,
    "total_duration_seconds": 191.0
  },
  "claims": [
    {
      "claim": "The form has 12 fillable fields",
      "type": "factual",
      "verified": true,
      "evidence": "Counted 12 fields in field_info.json"
    },
    {
      "claim": "All required fields were populated",
      "type": "quality",
      "verified": false,
      "evidence": "Reference section was left blank despite data being available"
    }
  ],
  "user_notes_summary": {
    "uncertainties": ["Used 2023 data, may be stale"],
    "needs_review": [],
    "workarounds": ["Fell back to text overlay for non-fillable fields"]
  },
  "eval_feedback": {
    "suggestions": [
      {
        "assertion": "The output includes the name 'John Smith'",
        "reason": "A hallucinated document that mentions the name would also pass — consider checking it appears as the primary contact with matching phone and email from the input"
      },
      {
        "reason": "No assertion checks whether the extracted phone numbers match the input — I observed incorrect numbers in the output that went uncaught"
      }
    ],
    "overall": "Assertions check presence but not correctness. Consider adding content verification."
  }
}
```

## Field Descriptions

- **expectations**: Array of graded expectations
  - **text**: The original expectation text
  - **passed**: Boolean - true if expectation passes
  - **evidence**: Specific quote or description supporting the verdict
- **summary**: Aggregate statistics
  - **passed**: Count of passed expectations
  - **failed**: Count of failed expectations
  - **total**: Total expectations evaluated
  - **pass_rate**: Fraction passed (0.0 to 1.0)
- **execution_metrics**: Copied from executor's metrics.json (if available)
  - **output_chars**: Total character count of output files (proxy for tokens)
  - **transcript_chars**: Character count of transcript
- **timing**: Wall clock timing from timing.json (if available)
  - **executor_duration_seconds**: Time spent in executor subagent
  - **total_duration_seconds**: Total elapsed time for the run
- **claims**: Extracted and verified claims from the output
  - **claim**: The statement being verified
  - **type**: "factual", "process", or "quality"
  - **verified**: Boolean - whether the claim holds
  - **evidence**: Supporting or contradicting evidence
- **user_notes_summary**: Issues flagged by the executor
  - **uncertainties**: Things the executor wasn't sure about
  - **needs_review**: Items requiring human attention
  - **workarounds**: Places where the skill didn't work as expected
- **eval_feedback**: Improvement suggestions for the evals (only when warranted)
  - **suggestions**: List of concrete suggestions, each with a `reason` and optionally an `assertion` it relates to
  - **overall**: Brief assessment — can be "No suggestions, evals look solid" if nothing to flag

## Guidelines

- **Be objective**: Base verdicts on evidence, not assumptions
- **Be specific**: Quote the exact text that supports your verdict
- **Be thorough**: Check both transcript and output files
- **Be consistent**: Apply the same standard to each expectation
- **Explain failures**: Make it clear why evidence was insufficient
- **No partial credit**: Each expectation is pass or fail, not partial

FILE:agents/comparator.md
# Blind Comparator Agent

Compare two outputs WITHOUT knowing which skill produced them.

## Role

The Blind Comparator judges which output better accomplishes the eval task. You receive two outputs labeled A and B, but you do NOT know which skill produced which. This prevents bias toward a particular skill or approach.

Your judgment is based purely on output quality and task completion.

## Inputs

You receive these parameters in your prompt:

- **output_a_path**: Path to the first output file or directory
- **output_b_path**: Path to the second output file or directory
- **eval_prompt**: The original task/prompt that was executed
- **expectations**: List of expectations to check (optional - may be empty)

## Process

### Step 1: Read Both Outputs

1. Examine output A (file or directory)
2. Examine output B (file or directory)
3. Note the type, structure, and content of each
4. If outputs are directories, examine all relevant files inside

### Step 2: Understand the Task

1. Read the eval_prompt carefully
2. Identify what the task requires:
   - What should be produced?
   - What qualities matter (accuracy, completeness, format)?
   - What would distinguish a good output from a poor one?

### Step 3: Generate Evaluation Rubric

Based on the task, generate a rubric with two dimensions:

**Content Rubric** (what the output contains):
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|-----------|----------|----------------|---------------|
| Correctness | Major errors | Minor errors | Fully correct |
| Completeness | Missing key elements | Mostly complete | All elements present |
| Accuracy | Significant inaccuracies | Minor inaccuracies | Accurate throughout |

**Structure Rubric** (how the output is organized):
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|-----------|----------|----------------|---------------|
| Organization | Disorganized | Reasonably organized | Clear, logical structure |
| Formatting | Inconsistent/broken | Mostly consistent | Professional, polished |
| Usability | Difficult to use | Usable with effort | Easy to use |

Adapt criteria to the specific task. For example:
- PDF form → "Field alignment", "Text readability", "Data placement"
- Document → "Section structure", "Heading hierarchy", "Paragraph flow"
- Data output → "Schema correctness", "Data types", "Completeness"

### Step 4: Evaluate Each Output Against the Rubric

For each output (A and B):

1. **Score each criterion** on the rubric (1-5 scale)
2. **Calculate dimension totals**: Content score, Structure score
3. **Calculate overall score**: Average of dimension scores, scaled to 1-10

### Step 5: Check Assertions (if provided)

If expectations are provided:

1. Check each expectation against output A
2. Check each expectation against output B
3. Count pass rates for each output
4. Use expectation scores as secondary evidence (not the primary decision factor)

### Step 6: Determine the Winner

Compare A and B based on (in priority order):

1. **Primary**: Overall rubric score (content + structure)
2. **Secondary**: Assertion pass rates (if applicable)
3. **Tiebreaker**: If truly equal, declare a TIE

Be decisive - ties should be rare. One output is usually better, even if marginally.

### Step 7: Write Comparison Results

Save results to a JSON file at the path specified (or `comparison.json` if not specified).

## Output Format

Write a JSON file with this structure:

```json
{
  "winner": "A",
  "reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
  "rubric": {
    "A": {
      "content": {
        "correctness": 5,
        "completeness": 5,
        "accuracy": 4
      },
      "structure": {
        "organization": 4,
        "formatting": 5,
        "usability": 4
      },
      "content_score": 4.7,
      "structure_score": 4.3,
      "overall_score": 9.0
    },
    "B": {
      "content": {
        "correctness": 3,
        "completeness": 2,
        "accuracy": 3
      },
      "structure": {
        "organization": 3,
        "formatting": 2,
        "usability": 3
      },
      "content_score": 2.7,
      "structure_score": 2.7,
      "overall_score": 5.4
    }
  },
  "output_quality": {
    "A": {
      "score": 9,
      "strengths": ["Complete solution", "Well-formatted", "All fields present"],
      "weaknesses": ["Minor style inconsistency in header"]
    },
    "B": {
      "score": 5,
      "strengths": ["Readable output", "Correct basic structure"],
      "weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
    }
  },
  "expectation_results": {
    "A": {
      "passed": 4,
      "total": 5,
      "pass_rate": 0.80,
      "details": [
        {"text": "Output includes name", "passed": true},
        {"text": "Output includes date", "passed": true},
        {"text": "Format is PDF", "passed": true},
        {"text": "Contains signature", "passed": false},
        {"text": "Readable text", "passed": true}
      ]
    },
    "B": {
      "passed": 3,
      "total": 5,
      "pass_rate": 0.60,
      "details": [
        {"text": "Output includes name", "passed": true},
        {"text": "Output includes date", "passed": false},
        {"text": "Format is PDF", "passed": true},
        {"text": "Contains signature", "passed": false},
        {"text": "Readable text", "passed": true}
      ]
    }
  }
}
```

If no expectations were provided, omit the `expectation_results` field entirely.

## Field Descriptions

- **winner**: "A", "B", or "TIE"
- **reasoning**: Clear explanation of why the winner was chosen (or why it's a tie)
- **rubric**: Structured rubric evaluation for each output
  - **content**: Scores for content criteria (correctness, completeness, accuracy)
  - **structure**: Scores for structure criteria (organization, formatting, usability)
  - **content_score**: Average of content criteria (1-5)
  - **structure_score**: Average of structure criteria (1-5)
  - **overall_score**: Combined score scaled to 1-10
- **output_quality**: Summary quality assessment
  - **score**: 1-10 rating (should match rubric overall_score)
  - **strengths**: List of positive aspects
  - **weaknesses**: List of issues or shortcomings
- **expectation_results**: (Only if expectations provided)
  - **passed**: Number of expectations that passed
  - **total**: Total number of expectations
  - **pass_rate**: Fraction passed (0.0 to 1.0)
  - **details**: Individual expectation results

## Guidelines

- **Stay blind**: DO NOT try to infer which skill produced which output. Judge purely on output quality.
- **Be specific**: Cite specific examples when explaining strengths and weaknesses.
- **Be decisive**: Choose a winner unless outputs are genuinely equivalent.
- **Output quality first**: Assertion scores are secondary to overall task completion.
- **Be objective**: Don't favor outputs based on style preferences; focus on correctness and completeness.
- **Explain your reasoning**: The reasoning field should make it clear why you chose the winner.
- **Handle edge cases**: If both outputs fail, pick the one that fails less badly. If both are excellent, pick the one that's marginally better.

FILE:agents/analyzer.md
# Post-hoc Analyzer Agent

Analyze blind comparison results to understand WHY the winner won and generate improvement suggestions.

## Role

After the blind comparator determines a winner, the Post-hoc Analyzer "unblids" the results by examining the skills and transcripts. The goal is to extract actionable insights: what made the winner better, and how can the loser be improved?

## Inputs

You receive these parameters in your prompt:

- **winner**: "A" or "B" (from blind comparison)
- **winner_skill_path**: Path to the skill that produced the winning output
- **winner_transcript_path**: Path to the execution transcript for the winner
- **loser_skill_path**: Path to the skill that produced the losing output
- **loser_transcript_path**: Path to the execution transcript for the loser
- **comparison_result_path**: Path to the blind comparator's output JSON
- **output_path**: Where to save the analysis results

## Process

### Step 1: Read Comparison Result

1. Read the blind comparator's output at comparison_result_path
2. Note the winning side (A or B), the reasoning, and any scores
3. Understand what the comparator valued in the winning output

### Step 2: Read Both Skills

1. Read the winner skill's SKILL.md and key referenced files
2. Read the loser skill's SKILL.md and key referenced files
3. Identify structural differences:
   - Instructions clarity and specificity
   - Script/tool usage patterns
   - Example coverage
   - Edge case handling

### Step 3: Read Both Transcripts

1. Read the winner's transcript
2. Read the loser's transcript
3. Compare execution patterns:
   - How closely did each follow their skill's instructions?
   - What tools were used differently?
   - Where did the loser diverge from optimal behavior?
   - Did either encounter errors or make recovery attempts?

### Step 4: Analyze Instruction Following

For each transcript, evaluate:
- Did the agent follow the skill's explicit instructions?
- Did the agent use the skill's provided tools/scripts?
- Were there missed opportunities to leverage skill content?
- Did the agent add unnecessary steps not in the skill?

Score instruction following 1-10 and note specific issues.

### Step 5: Identify Winner Strengths

Determine what made the winner better:
- Clearer instructions that led to better behavior?
- Better scripts/tools that produced better output?
- More comprehensive examples that guided edge cases?
- Better error handling guidance?

Be specific. Quote from skills/transcripts where relevant.

### Step 6: Identify Loser Weaknesses

Determine what held the loser back:
- Ambiguous instructions that led to suboptimal choices?
- Missing tools/scripts that forced workarounds?
- Gaps in edge case coverage?
- Poor error handling that caused failures?

### Step 7: Generate Improvement Suggestions

Based on the analysis, produce actionable suggestions for improving the loser skill:
- Specific instruction changes to make
- Tools/scripts to add or modify
- Examples to include
- Edge cases to address

Prioritize by impact. Focus on changes that would have changed the outcome.

### Step 8: Write Analysis Results

Save structured analysis to `{output_path}`.

## Output Format

Write a JSON file with this structure:

```json
{
  "comparison_summary": {
    "winner": "A",
    "winner_skill": "path/to/winner/skill",
    "loser_skill": "path/to/loser/skill",
    "comparator_reasoning": "Brief summary of why comparator chose winner"
  },
  "winner_strengths": [
    "Clear step-by-step instructions for handling multi-page documents",
    "Included validation script that caught formatting errors",
    "Explicit guidance on fallback behavior when OCR fails"
  ],
  "loser_weaknesses": [
    "Vague instruction 'process the document appropriately' led to inconsistent behavior",
    "No script for validation, agent had to improvise and made errors",
    "No guidance on OCR failure, agent gave up instead of trying alternatives"
  ],
  "instruction_following": {
    "winner": {
      "score": 9,
      "issues": [
        "Minor: skipped optional logging step"
      ]
    },
    "loser": {
      "score": 6,
      "issues": [
        "Did not use the skill's formatting template",
        "Invented own approach instead of following step 3",
        "Missed the 'always validate output' instruction"
      ]
    }
  },
  "improvement_suggestions": [
    {
      "priority": "high",
      "category": "instructions",
      "suggestion": "Replace 'process the document appropriately' with explicit steps: 1) Extract text, 2) Identify sections, 3) Format per template",
      "expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
    },
    {
      "priority": "high",
      "category": "tools",
      "suggestion": "Add validate_output.py script similar to winner skill's validation approach",
      "expected_impact": "Would catch formatting errors before final output"
    },
    {
      "priority": "medium",
      "category": "error_handling",
      "suggestion": "Add fallback instructions: 'If OCR fails, try: 1) different resolution, 2) image preprocessing, 3) manual extraction'",
      "expected_impact": "Would prevent early failure on difficult documents"
    }
  ],
  "transcript_insights": {
    "winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script -> Fixed 2 issues -> Produced output",
    "loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods -> No validation -> Output had errors"
  }
}
```

## Guidelines

- **Be specific**: Quote from skills and transcripts, don't just say "instructions were unclear"
- **Be actionable**: Suggestions should be concrete changes, not vague advice
- **Focus on skill improvements**: The goal is to improve the losing skill, not critique the agent
- **Prioritize by impact**: Which changes would most likely have changed the outcome?
- **Consider causation**: Did the skill weakness actually cause the worse output, or is it incidental?
- **Stay objective**: Analyze what happened, don't editorialize
- **Think about generalization**: Would this improvement help on other evals too?

## Categories for Suggestions

Use these categories to organize improvement suggestions:

| Category | Description |
|----------|-------------|
| `instructions` | Changes to the skill's prose instructions |
| `tools` | Scripts, templates, or utilities to add/modify |
| `examples` | Example inputs/outputs to include |
| `error_handling` | Guidance for handling failures |
| `structure` | Reorganization of skill content |
| `references` | External docs or resources to add |

## Priority Levels

- **high**: Would likely change the outcome of this comparison
- **medium**: Would improve quality but may not change win/loss
- **low**: Nice to have, marginal improvement

---

# Analyzing Benchmark Results

When analyzing benchmark results, the analyzer's purpose is to **surface patterns and anomalies** across multiple runs, not suggest skill improvements.

## Role

Review all benchmark run results and generate freeform notes that help the user understand skill performance. Focus on patterns that wouldn't be visible from aggregate metrics alone.

## Inputs

You receive these parameters in your prompt:

- **benchmark_data_path**: Path to the in-progress benchmark.json with all run results
- **skill_path**: Path to the skill being benchmarked
- **output_path**: Where to save the notes (as JSON array of strings)

## Process

### Step 1: Read Benchmark Data

1. Read the benchmark.json containing all run results
2. Note the configurations tested (with_skill, without_skill)
3. Understand the run_summary aggregates already calculated

### Step 2: Analyze Per-Assertion Patterns

For each expectation across all runs:
- Does it **always pass** in both configurations? (may not differentiate skill value)
- Does it **always fail** in both configurations? (may be broken or beyond capability)
- Does it **always pass with skill but fail without**? (skill clearly adds value here)
- Does it **always fail with skill but pass without**? (skill may be hurting)
- Is it **highly variable**? (flaky expectation or non-deterministic behavior)

### Step 3: Analyze Cross-Eval Patterns

Look for patterns across evals:
- Are certain eval types consistently harder/easier?
- Do some evals show high variance while others are stable?
- Are there surprising results that contradict expectations?

### Step 4: Analyze Metrics Patterns

Look at time_seconds, tokens, tool_calls:
- Does the skill significantly increase execution time?
- Is there high variance in resource usage?
- Are there outlier runs that skew the aggregates?

### Step 5: Generate Notes

Write freeform observations as a list of strings. Each note should:
- State a specific observation
- Be grounded in the data (not speculation)
- Help the user understand something the aggregate metrics don't show

Examples:
- "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value"
- "Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure that may be flaky"
- "Without-skill runs consistently fail on table extraction expectations (0% pass rate)"
- "Skill adds 13s average execution time but improves pass rate by 50%"
- "Token usage is 80% higher with skill, primarily due to script output parsing"
- "All 3 without-skill runs for eval 1 produced empty output"

### Step 6: Write Notes

Save notes to `{output_path}` as a JSON array of strings:

```json
[
  "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
  "Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure",
  "Without-skill runs consistently fail on table extraction expectations",
  "Skill adds 13s average execution time but improves pass rate by 50%"
]
```

## Guidelines

**DO:**
- Report what you observe in the data
- Be specific about which evals, expectations, or runs you're referring to
- Note patterns that aggregate metrics would hide
- Provide context that helps interpret the numbers

**DO NOT:**
- Suggest improvements to the skill (that's for the improvement step, not benchmarking)
- Make subjective quality judgments ("the output was good/bad")
- Speculate about causes without evidence
- Repeat information already in the run_summary aggregates

FILE:references/schemas.md
# JSON Schemas

This document defines the JSON schemas used by skill-creator.

---

## evals.json

Defines the evals for a skill. Located at `evals/evals.json` within the skill directory.

```json
{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's example prompt",
      "expected_output": "Description of expected result",
      "files": ["evals/files/sample1.pdf"],
      "expectations": [
        "The output includes X",
        "The skill used script Y"
      ]
    }
  ]
}
```

**Fields:**
- `skill_name`: Name matching the skill's frontmatter
- `evals[].id`: Unique integer identifier
- `evals[].prompt`: The task to execute
- `evals[].expected_output`: Human-readable description of success
- `evals[].files`: Optional list of input file paths (relative to skill root)
- `evals[].expectations`: List of verifiable statements

---

## history.json

Tracks version progression in Improve mode. Located at workspace root.

```json
{
  "started_at": "2026-01-15T10:30:00Z",
  "skill_name": "pdf",
  "current_best": "v2",
  "iterations": [
    {
      "version": "v0",
      "parent": null,
      "expectation_pass_rate": 0.65,
      "grading_result": "baseline",
      "is_current_best": false
    },
    {
      "version": "v1",
      "parent": "v0",
      "expectation_pass_rate": 0.75,
      "grading_result": "won",
      "is_current_best": false
    },
    {
      "version": "v2",
      "parent": "v1",
      "expectation_pass_rate": 0.85,
      "grading_result": "won",
      "is_current_best": true
    }
  ]
}
```

**Fields:**
- `started_at`: ISO timestamp of when improvement started
- `skill_name`: Name of the skill being improved
- `current_best`: Version identifier of the best performer
- `iterations[].version`: Version identifier (v0, v1, ...)
- `iterations[].parent`: Parent version this was derived from
- `iterations[].expectation_pass_rate`: Pass rate from grading
- `iterations[].grading_result`: "baseline", "won", "lost", or "tie"
- `iterations[].is_current_best`: Whether this is the current best version

---

## grading.json

Output from the grader agent. Located at `<run-dir>/grading.json`.

```json
{
  "expectations": [
    {
      "text": "The output includes the name 'John Smith'",
      "passed": true,
      "evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'"
    },
    {
      "text": "The spreadsheet has a SUM formula in cell B10",
      "passed": false,
      "evidence": "No spreadsheet was created. The output was a text file."
    }
  ],
  "summary": {
    "passed": 2,
    "failed": 1,
    "total": 3,
    "pass_rate": 0.67
  },
  "execution_metrics": {
    "tool_calls": {
      "Read": 5,
      "Write": 2,
      "Bash": 8
    },
    "total_tool_calls": 15,
    "total_steps": 6,
    "errors_encountered": 0,
    "output_chars": 12450,
    "transcript_chars": 3200
  },
  "timing": {
    "executor_duration_seconds": 165.0,
    "grader_duration_seconds": 26.0,
    "total_duration_seconds": 191.0
  },
  "claims": [
    {
      "claim": "The form has 12 fillable fields",
      "type": "factual",
      "verified": true,
      "evidence": "Counted 12 fields in field_info.json"
    }
  ],
  "user_notes_summary": {
    "uncertainties": ["Used 2023 data, may be stale"],
    "needs_review": [],
    "workarounds": ["Fell back to text overlay for non-fillable fields"]
  },
  "eval_feedback": {
    "suggestions": [
      {
        "assertion": "The output includes the name 'John Smith'",
        "reason": "A hallucinated document that mentions the name would also pass"
      }
    ],
    "overall": "Assertions check presence but not correctness."
  }
}
```

**Fields:**
- `expectations[]`: Graded expectations with evidence
- `summary`: Aggregate pass/fail counts
- `execution_metrics`: Tool usage and output size (from executor's metrics.json)
- `timing`: Wall clock timing (from timing.json)
- `claims`: Extracted and verified claims from the output
- `user_notes_summary`: Issues flagged by the executor
- `eval_feedback`: (optional) Improvement suggestions for the evals, only present when the grader identifies issues worth raising

---

## metrics.json

Output from the executor agent. Located at `<run-dir>/outputs/metrics.json`.

```json
{
  "tool_calls": {
    "Read": 5,
    "Write": 2,
    "Bash": 8,
    "Edit": 1,
    "Glob": 2,
    "Grep": 0
  },
  "total_tool_calls": 18,
  "total_steps": 6,
  "files_created": ["filled_form.pdf", "field_values.json"],
  "errors_encountered": 0,
  "output_chars": 12450,
  "transcript_chars": 3200
}
```

**Fields:**
- `tool_calls`: Count per tool type
- `total_tool_calls`: Sum of all tool calls
- `total_steps`: Number of major execution steps
- `files_created`: List of output files created
- `errors_encountered`: Number of errors during execution
- `output_chars`: Total character count of output files
- `transcript_chars`: Character count of transcript

---

## timing.json

Wall clock timing for a run. Located at `<run-dir>/timing.json`.

**How to capture:** When a subagent task completes, the task notification includes `total_tokens` and `duration_ms`. Save these immediately — they are not persisted anywhere else and cannot be recovered after the fact.

```json
{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3,
  "executor_start": "2026-01-15T10:30:00Z",
  "executor_end": "2026-01-15T10:32:45Z",
  "executor_duration_seconds": 165.0,
  "grader_start": "2026-01-15T10:32:46Z",
  "grader_end": "2026-01-15T10:33:12Z",
  "grader_duration_seconds": 26.0
}
```

---

## benchmark.json

Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.

```json
{
  "metadata": {
    "skill_name": "pdf",
    "skill_path": "/path/to/pdf",
    "executor_model": "claude-sonnet-4-20250514",
    "analyzer_model": "most-capable-model",
    "timestamp": "2026-01-15T10:30:00Z",
    "evals_run": [1, 2, 3],
    "runs_per_configuration": 3
  },

  "runs": [
    {
      "eval_id": 1,
      "eval_name": "Ocean",
      "configuration": "with_skill",
      "run_number": 1,
      "result": {
        "pass_rate": 0.85,
        "passed": 6,
        "failed": 1,
        "total": 7,
        "time_seconds": 42.5,
        "tokens": 3800,
        "tool_calls": 18,
        "errors": 0
      },
      "expectations": [
        {"text": "...", "passed": true, "evidence": "..."}
      ],
      "notes": [
        "Used 2023 data, may be stale",
        "Fell back to text overlay for non-fillable fields"
      ]
    }
  ],

  "run_summary": {
    "with_skill": {
      "pass_rate": {"mean": 0.85, "stddev": 0.05, "min": 0.80, "max": 0.90},
      "time_seconds": {"mean": 45.0, "stddev": 12.0, "min": 32.0, "max": 58.0},
      "tokens": {"mean": 3800, "stddev": 400, "min": 3200, "max": 4100}
    },
    "without_skill": {
      "pass_rate": {"mean": 0.35, "stddev": 0.08, "min": 0.28, "max": 0.45},
      "time_seconds": {"mean": 32.0, "stddev": 8.0, "min": 24.0, "max": 42.0},
      "tokens": {"mean": 2100, "stddev": 300, "min": 1800, "max": 2500}
    },
    "delta": {
      "pass_rate": "+0.50",
      "time_seconds": "+13.0",
      "tokens": "+1700"
    }
  },

  "notes": [
    "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
    "Eval 3 shows high variance (50% ± 40%) - may be flaky or model-dependent",
    "Without-skill runs consistently fail on table extraction expectations",
    "Skill adds 13s average execution time but improves pass rate by 50%"
  ]
}
```

**Fields:**
- `metadata`: Information about the benchmark run
  - `skill_name`: Name of the skill
  - `timestamp`: When the benchmark was run
  - `evals_run`: List of eval names or IDs
  - `runs_per_configuration`: Number of runs per config (e.g. 3)
- `runs[]`: Individual run results
  - `eval_id`: Numeric eval identifier
  - `eval_name`: Human-readable eval name (used as section header in the viewer)
  - `configuration`: Must be `"with_skill"` or `"without_skill"` (the viewer uses this exact string for grouping and color coding)
  - `run_number`: Integer run number (1, 2, 3...)
  - `result`: Nested object with `pass_rate`, `passed`, `total`, `time_seconds`, `tokens`, `errors`
- `run_summary`: Statistical aggregates per configuration
  - `with_skill` / `without_skill`: Each contains `pass_rate`, `time_seconds`, `tokens` objects with `mean` and `stddev` fields
  - `delta`: Difference strings like `"+0.50"`, `"+13.0"`, `"+1700"`
- `notes`: Freeform observations from the analyzer

**Important:** The viewer reads these field names exactly. Using `config` instead of `configuration`, or putting `pass_rate` at the top level of a run instead of nested under `result`, will cause the viewer to show empty/zero values. Always reference this schema when generating benchmark.json manually.

---

## comparison.json

Output from blind comparator. Located at `<grading-dir>/comparison-N.json`.

```json
{
  "winner": "A",
  "reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
  "rubric": {
    "A": {
      "content": {
        "correctness": 5,
        "completeness": 5,
        "accuracy": 4
      },
      "structure": {
        "organization": 4,
        "formatting": 5,
        "usability": 4
      },
      "content_score": 4.7,
      "structure_score": 4.3,
      "overall_score": 9.0
    },
    "B": {
      "content": {
        "correctness": 3,
        "completeness": 2,
        "accuracy": 3
      },
      "structure": {
        "organization": 3,
        "formatting": 2,
        "usability": 3
      },
      "content_score": 2.7,
      "structure_score": 2.7,
      "overall_score": 5.4
    }
  },
  "output_quality": {
    "A": {
      "score": 9,
      "strengths": ["Complete solution", "Well-formatted", "All fields present"],
      "weaknesses": ["Minor style inconsistency in header"]
    },
    "B": {
      "score": 5,
      "strengths": ["Readable output", "Correct basic structure"],
      "weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
    }
  },
  "expectation_results": {
    "A": {
      "passed": 4,
      "total": 5,
      "pass_rate": 0.80,
      "details": [
        {"text": "Output includes name", "passed": true}
      ]
    },
    "B": {
      "passed": 3,
      "total": 5,
      "pass_rate": 0.60,
      "details": [
        {"text": "Output includes name", "passed": true}
      ]
    }
  }
}
```

---

## analysis.json

Output from post-hoc analyzer. Located at `<grading-dir>/analysis.json`.

```json
{
  "comparison_summary": {
    "winner": "A",
    "winner_skill": "path/to/winner/skill",
    "loser_skill": "path/to/loser/skill",
    "comparator_reasoning": "Brief summary of why comparator chose winner"
  },
  "winner_strengths": [
    "Clear step-by-step instructions for handling multi-page documents",
    "Included validation script that caught formatting errors"
  ],
  "loser_weaknesses": [
    "Vague instruction 'process the document appropriately' led to inconsistent behavior",
    "No script for validation, agent had to improvise"
  ],
  "instruction_following": {
    "winner": {
      "score": 9,
      "issues": ["Minor: skipped optional logging step"]
    },
    "loser": {
      "score": 6,
      "issues": [
        "Did not use the skill's formatting template",
        "Invented own approach instead of following step 3"
      ]
    }
  },
  "improvement_suggestions": [
    {
      "priority": "high",
      "category": "instructions",
      "suggestion": "Replace 'process the document appropriately' with explicit steps",
      "expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
    }
  ],
  "transcript_insights": {
    "winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script",
    "loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods"
  }
}
```

FILE:eval-viewer/generate_review.py
#!/usr/bin/env python3
"""Generate and serve a review page for eval results.

Reads the workspace directory, discovers runs (directories with outputs/),
embeds all output data into a self-contained HTML page, and serves it via
a tiny HTTP server. Feedback auto-saves to feedback.json in the workspace.

Usage:
    python generate_review.py <workspace-path> [--port PORT] [--skill-name NAME]
    python generate_review.py <workspace-path> --previous-feedback /path/to/old/feedback.json

No dependencies beyond the Python stdlib are required.
"""

import argparse
import base64
import json
import mimetypes
import os
import re
import signal
import subprocess
import sys
import time
import webbrowser
from functools import partial
from http.server import HTTPServer, BaseHTTPRequestHandler
from pathlib import Path

# Files to exclude from output listings
METADATA_FILES = {"transcript.md", "user_notes.md", "metrics.json"}

# Extensions we render as inline text
TEXT_EXTENSIONS = {
    ".txt", ".md", ".json", ".csv", ".py", ".js", ".ts", ".tsx", ".jsx",
    ".yaml", ".yml", ".xml", ".html", ".css", ".sh", ".rb", ".go", ".rs",
    ".java", ".c", ".cpp", ".h", ".hpp", ".sql", ".r", ".toml",
}

# Extensions we render as inline images
IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"}

# MIME type overrides for common types
MIME_OVERRIDES = {
    ".svg": "image/svg+xml",
    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
}


def get_mime_type(path: Path) -> str:
    ext = path.suffix.lower()
    if ext in MIME_OVERRIDES:
        return MIME_OVERRIDES[ext]
    mime, _ = mimetypes.guess_type(str(path))
    return mime or "application/octet-stream"


def find_runs(workspace: Path) -> list[dict]:
    """Recursively find directories that contain an outputs/ subdirectory."""
    runs: list[dict] = []
    _find_runs_recursive(workspace, workspace, runs)
    runs.sort(key=lambda r: (r.get("eval_id", float("inf")), r["id"]))
    return runs


def _find_runs_recursive(root: Path, current: Path, runs: list[dict]) -> None:
    if not current.is_dir():
        return

    outputs_dir = current / "outputs"
    if outputs_dir.is_dir():
        run = build_run(root, current)
        if run:
            runs.append(run)
        return

    skip = {"node_modules", ".git", "__pycache__", "skill", "inputs"}
    for child in sorted(current.iterdir()):
        if child.is_dir() and child.name not in skip:
            _find_runs_recursive(root, child, runs)


def build_run(root: Path, run_dir: Path) -> dict | None:
    """Build a run dict with prompt, outputs, and grading data."""
    prompt = ""
    eval_id = None

    # Try eval_metadata.json
    for candidate in [run_dir / "eval_metadata.json", run_dir.parent / "eval_metadata.json"]:
        if candidate.exists():
            try:
                metadata = json.loads(candidate.read_text())
                prompt = metadata.get("prompt", "")
                eval_id = metadata.get("eval_id")
            except (json.JSONDecodeError, OSError):
                pass
            if prompt:
                break

    # Fall back to transcript.md
    if not prompt:
        for candidate in [run_dir / "transcript.md", run_dir / "outputs" / "transcript.md"]:
            if candidate.exists():
                try:
                    text = candidate.read_text()
                    match = re.search(r"## Eval Prompt\n\n([\s\S]*?)(?=\n##|$)", text)
                    if match:
                        prompt = match.group(1).strip()
                except OSError:
                    pass
                if prompt:
                    break

    if not prompt:
        prompt = "(No prompt found)"

    run_id = str(run_dir.relative_to(root)).replace("/", "-").replace("\\", "-")

    # Collect output files
    outputs_dir = run_dir / "outputs"
    output_files: list[dict] = []
    if outputs_dir.is_dir():
        for f in sorted(outputs_dir.iterdir()):
            if f.is_file() and f.name not in METADATA_FILES:
                output_files.append(embed_file(f))

    # Load grading if present
    grading = None
    for candidate in [run_dir / "grading.json", run_dir.parent / "grading.json"]:
        if candidate.exists():
            try:
                grading = json.loads(candidate.read_text())
            except (json.JSONDecodeError, OSError):
                pass
            if grading:
                break

    return {
        "id": run_id,
        "prompt": prompt,
        "eval_id": eval_id,
        "outputs": output_files,
        "grading": grading,
    }


def embed_file(path: Path) -> dict:
    """Read a file and return an embedded representation."""
    ext = path.suffix.lower()
    mime = get_mime_type(path)

    if ext in TEXT_EXTENSIONS:
        try:
            content = path.read_text(errors="replace")
        except OSError:
            content = "(Error reading file)"
        return {
            "name": path.name,
            "type": "text",
            "content": content,
        }
    elif ext in IMAGE_EXTENSIONS:
        try:
            raw = path.read_bytes()
            b64 = base64.b64encode(raw).decode("ascii")
        except OSError:
            return {"name": path.name, "type": "error", "content": "(Error reading file)"}
        return {
            "name": path.name,
            "type": "image",
            "mime": mime,
            "data_uri": f"data:{mime};base64,{b64}",
        }
    elif ext == ".pdf":
        try:
            raw = path.read_bytes()
            b64 = base64.b64encode(raw).decode("ascii")
        except OSError:
            return {"name": path.name, "type": "error", "content": "(Error reading file)"}
        return {
            "name": path.name,
            "type": "pdf",
            "data_uri": f"data:{mime};base64,{b64}",
        }
    elif ext == ".xlsx":
        try:
            raw = path.read_bytes()
            b64 = base64.b64encode(raw).decode("ascii")
        except OSError:
            return {"name": path.name, "type": "error", "content": "(Error reading file)"}
        return {
            "name": path.name,
            "type": "xlsx",
            "data_b64": b64,
        }
    else:
        # Binary / unknown — base64 download link
        try:
            raw = path.read_bytes()
            b64 = base64.b64encode(raw).decode("ascii")
        except OSError:
            return {"name": path.name, "type": "error", "content": "(Error reading file)"}
        return {
            "name": path.name,
            "type": "binary",
            "mime": mime,
            "data_uri": f"data:{mime};base64,{b64}",
        }


def load_previous_iteration(workspace: Path) -> dict[str, dict]:
    """Load previous iteration's feedback and outputs.

    Returns a map of run_id -> {"feedback": str, "outputs": list[dict]}.
    """
    result: dict[str, dict] = {}

    # Load feedback
    feedback_map: dict[str, str] = {}
    feedback_path = workspace / "feedback.json"
    if feedback_path.exists():
        try:
            data = json.loads(feedback_path.read_text())
            feedback_map = {
                r["run_id"]: r["feedback"]
                for r in data.get("reviews", [])
                if r.get("feedback", "").strip()
            }
        except (json.JSONDecodeError, OSError, KeyError):
            pass

    # Load runs (to get outputs)
    prev_runs = find_runs(workspace)
    for run in prev_runs:
        result[run["id"]] = {
            "feedback": feedback_map.get(run["id"], ""),
            "outputs": run.get("outputs", []),
        }

    # Also add feedback for run_ids that had feedback but no matching run
    for run_id, fb in feedback_map.items():
        if run_id not in result:
            result[run_id] = {"feedback": fb, "outputs": []}

    return result


def generate_html(
    runs: list[dict],
    skill_name: str,
    previous: dict[str, dict] | None = None,
    benchmark: dict | None = None,
) -> str:
    """Generate the complete standalone HTML page with embedded data."""
    template_path = Path(__file__).parent / "viewer.html"
    template = template_path.read_text()

    # Build previous_feedback and previous_outputs maps for the template
    previous_feedback: dict[str, str] = {}
    previous_outputs: dict[str, list[dict]] = {}
    if previous:
        for run_id, data in previous.items():
            if data.get("feedback"):
                previous_feedback[run_id] = data["feedback"]
            if data.get("outputs"):
                previous_outputs[run_id] = data["outputs"]

    embedded = {
        "skill_name": skill_name,
        "runs": runs,
        "previous_feedback": previous_feedback,
        "previous_outputs": previous_outputs,
    }
    if benchmark:
        embedded["benchmark"] = benchmark

    data_json = json.dumps(embedded)

    return template.replace("/*__EMBEDDED_DATA__*/", f"const EMBEDDED_DATA = {data_json};")


# ---------------------------------------------------------------------------
# HTTP server (stdlib only, zero dependencies)
# ---------------------------------------------------------------------------

def _kill_port(port: int) -> None:
    """Kill any process listening on the given port."""
    try:
        result = subprocess.run(
            ["lsof", "-ti", f":{port}"],
            capture_output=True, text=True, timeout=5,
        )
        for pid_str in result.stdout.strip().split("\n"):
            if pid_str.strip():
                try:
                    os.kill(int(pid_str.strip()), signal.SIGTERM)
                except (ProcessLookupError, ValueError):
                    pass
        if result.stdout.strip():
            time.sleep(0.5)
    except subprocess.TimeoutExpired:
        pass
    except FileNotFoundError:
        print("Note: lsof not found, cannot check if port is in use", file=sys.stderr)

class ReviewHandler(BaseHTTPRequestHandler):
    """Serves the review HTML and handles feedback saves.

    Regenerates the HTML on each page load so that refreshing the browser
    picks up new eval outputs without restarting the server.
    """

    def __init__(
        self,
        workspace: Path,
        skill_name: str,
        feedback_path: Path,
        previous: dict[str, dict],
        benchmark_path: Path | None,
        *args,
        **kwargs,
    ):
        self.workspace = workspace
        self.skill_name = skill_name
        self.feedback_path = feedback_path
        self.previous = previous
        self.benchmark_path = benchmark_path
        super().__init__(*args, **kwargs)

    def do_GET(self) -> None:
        if self.path == "/" or self.path == "/index.html":
            # Regenerate HTML on each request (re-scans workspace for new outputs)
            runs = find_runs(self.workspace)
            benchmark = None
            if self.benchmark_path and self.benchmark_path.exists():
                try:
                    benchmark = json.loads(self.benchmark_path.read_text())
                except (json.JSONDecodeError, OSError):
                    pass
            html = generate_html(runs, self.skill_name, self.previous, benchmark)
            content = html.encode("utf-8")
            self.send_response(200)
            self.send_header("Content-Type", "text/html; charset=utf-8")
            self.send_header("Content-Length", str(len(content)))
            self.end_headers()
            self.wfile.write(content)
        elif self.path == "/api/feedback":
            data = b"{}"
            if self.feedback_path.exists():
                data = self.feedback_path.read_bytes()
            self.send_response(200)
            self.send_header("Content-Type", "application/json")
            self.send_header("Content-Length", str(len(data)))
            self.end_headers()
            self.wfile.write(data)
        else:
            self.send_error(404)

    def do_POST(self) -> None:
        if self.path == "/api/feedback":
            length = int(self.headers.get("Content-Length", 0))
            body = self.rfile.read(length)
            try:
                data = json.loads(body)
                if not isinstance(data, dict) or "reviews" not in data:
                    raise ValueError("Expected JSON object with 'reviews' key")
                self.feedback_path.write_text(json.dumps(data, indent=2) + "\n")
                resp = b'{"ok":true}'
                self.send_response(200)
            except (json.JSONDecodeError, OSError, ValueError) as e:
                resp = json.dumps({"error": str(e)}).encode()
                self.send_response(500)
            self.send_header("Content-Type", "application/json")
            self.send_header("Content-Length", str(len(resp)))
            self.end_headers()
            self.wfile.write(resp)
        else:
            self.send_error(404)

    def log_message(self, format: str, *args: object) -> None:
        # Suppress request logging to keep terminal clean
        pass


def main() -> None:
    parser = argparse.ArgumentParser(description="Generate and serve eval review")
    parser.add_argument("workspace", type=Path, help="Path to workspace directory")
    parser.add_argument("--port", "-p", type=int, default=3117, help="Server port (default: 3117)")
    parser.add_argument("--skill-name", "-n", type=str, default=None, help="Skill name for header")
    parser.add_argument(
        "--previous-workspace", type=Path, default=None,
        help="Path to previous iteration's workspace (shows old outputs and feedback as context)",
    )
    parser.add_argument(
        "--benchmark", type=Path, default=None,
        help="Path to benchmark.json to show in the Benchmark tab",
    )
    parser.add_argument(
        "--static", "-s", type=Path, default=None,
        help="Write standalone HTML to this path instead of starting a server",
    )
    args = parser.parse_args()

    workspace = args.workspace.resolve()
    if not workspace.is_dir():
        print(f"Error: {workspace} is not a directory", file=sys.stderr)
        sys.exit(1)

    runs = find_runs(workspace)
    if not runs:
        print(f"No runs found in {workspace}", file=sys.stderr)
        sys.exit(1)

    skill_name = args.skill_name or workspace.name.replace("-workspace", "")
    feedback_path = workspace / "feedback.json"

    previous: dict[str, dict] = {}
    if args.previous_workspace:
        previous = load_previous_iteration(args.previous_workspace.resolve())

    benchmark_path = args.benchmark.resolve() if args.benchmark else None
    benchmark = None
    if benchmark_path and benchmark_path.exists():
        try:
            benchmark = json.loads(benchmark_path.read_text())
        except (json.JSONDecodeError, OSError):
            pass

    if args.static:
        html = generate_html(runs, skill_name, previous, benchmark)
        args.static.parent.mkdir(parents=True, exist_ok=True)
        args.static.write_text(html)
        print(f"\n  Static viewer written to: {args.static}\n")
        sys.exit(0)

    # Kill any existing process on the target port
    port = args.port
    _kill_port(port)
    handler = partial(ReviewHandler, workspace, skill_name, feedback_path, previous, benchmark_path)
    try:
        server = HTTPServer(("127.0.0.1", port), handler)
    except OSError:
        # Port still in use after kill attempt — find a free one
        server = HTTPServer(("127.0.0.1", 0), handler)
        port = server.server_address[1]

    url = f"http://localhost:{port}"
    print(f"\n  Eval Viewer")
    print(f"  ─────────────────────────────────")
    print(f"  URL:       {url}")
    print(f"  Workspace: {workspace}")
    print(f"  Feedback:  {feedback_path}")
    if previous:
        print(f"  Previous:  {args.previous_workspace} ({len(previous)} runs)")
    if benchmark_path:
        print(f"  Benchmark: {benchmark_path}")
    print(f"\n  Press Ctrl+C to stop.\n")

    webbrowser.open(url)

    try:
        server.serve_forever()
    except KeyboardInterrupt:
        print("\nStopped.")
        server.server_close()


if __name__ == "__main__":
    main()

FILE:eval-viewer/viewer.html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Eval Review</title>
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
  <script src="https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js" integrity="sha384-EnyY0/GSHQGSxSgMwaIPzSESbqoOLSexfnSMN2AP+39Ckmn92stwABZynq1JyzdT" crossorigin="anonymous"></script>
  <style>
    :root {
      --bg: #faf9f5;
      --surface: #ffffff;
      --border: #e8e6dc;
      --text: #141413;
      --text-muted: #b0aea5;
      --accent: #d97757;
      --accent-hover: #c4613f;
      --green: #788c5d;
      --green-bg: #eef2e8;
      --red: #c44;
      --red-bg: #fceaea;
      --header-bg: #141413;
      --header-text: #faf9f5;
      --radius: 6px;
    }

    * { box-sizing: border-box; margin: 0; padding: 0; }

    body {
      font-family: 'Lora', Georgia, serif;
      background: var(--bg);
      color: var(--text);
      height: 100vh;
      display: flex;
      flex-direction: column;
    }

    /* ---- Header ---- */
    .header {
      background: var(--header-bg);
      color: var(--header-text);
      padding: 1rem 2rem;
      display: flex;
      justify-content: space-between;
      align-items: center;
      flex-shrink: 0;
    }
    .header h1 {
      font-family: 'Poppins', sans-serif;
      font-size: 1.25rem;
      font-weight: 600;
    }
    .header .instructions {
      font-size: 0.8rem;
      opacity: 0.7;
      margin-top: 0.25rem;
    }
    .header .progress {
      font-size: 0.875rem;
      opacity: 0.8;
      text-align: right;
    }

    /* ---- Main content ---- */
    .main {
      flex: 1;
      overflow-y: auto;
      padding: 1.5rem 2rem;
      display: flex;
      flex-direction: column;
      gap: 1.25rem;
    }

    /* ---- Sections ---- */
    .section {
      background: var(--surface);
      border: 1px solid var(--border);
      border-radius: var(--radius);
      flex-shrink: 0;
    }
    .section-header {
      font-family: 'Poppins', sans-serif;
      padding: 0.75rem 1rem;
      font-size: 0.75rem;
      font-weight: 500;
      text-transform: uppercase;
      letter-spacing: 0.05em;
      color: var(--text-muted);
      border-bottom: 1px solid var(--border);
      background: var(--bg);
    }
    .section-body {
      padding: 1rem;
    }

    /* ---- Config badge ---- */
    .config-badge {
      display: inline-block;
      padding: 0.2rem 0.625rem;
      border-radius: 9999px;
      font-family: 'Poppins', sans-serif;
      font-size: 0.6875rem;
      font-weight: 600;
      text-transform: uppercase;
      letter-spacing: 0.03em;
      margin-left: 0.75rem;
      vertical-align: middle;
    }
    .config-badge.config-primary {
      background: rgba(33, 150, 243, 0.12);
      color: #1976d2;
    }
    .config-badge.config-baseline {
      background: rgba(255, 193, 7, 0.15);
      color: #f57f17;
    }

    /* ---- Prompt ---- */
    .prompt-text {
      white-space: pre-wrap;
      font-size: 0.9375rem;
      line-height: 1.6;
    }

    /* ---- Outputs ---- */
    .output-file {
      border: 1px solid var(--border);
      border-radius: var(--radius);
      overflow: hidden;
    }
    .output-file + .output-file {
      margin-top: 1rem;
    }
    .output-file-header {
      padding: 0.5rem 0.75rem;
      font-size: 0.8rem;
      font-weight: 600;
      color: var(--text-muted);
      background: var(--bg);
      border-bottom: 1px solid var(--border);
      font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace;
      display: flex;
      justify-content: space-between;
      align-items: center;
    }
    .output-file-header .dl-btn {
      font-size: 0.7rem;
      color: var(--accent);
      text-decoration: none;
      cursor: pointer;
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
      font-weight: 500;
      opacity: 0.8;
    }
    .output-file-header .dl-btn:hover {
      opacity: 1;
      text-decoration: underline;
    }
    .output-file-content {
      padding: 0.75rem;
      overflow-x: auto;
    }
    .output-file-content pre {
      font-size: 0.8125rem;
      line-height: 1.5;
      white-space: pre-wrap;
      word-break: break-word;
      font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace;
    }
    .output-file-content img {
      max-width: 100%;
      height: auto;
      border-radius: 4px;
    }
    .output-file-content iframe {
      width: 100%;
      height: 600px;
      border: none;
    }
    .output-file-content table {
      border-collapse: collapse;
      font-size: 0.8125rem;
      width: 100%;
    }
    .output-file-content table td,
    .output-file-content table th {
      border: 1px solid var(--border);
      padding: 0.375rem 0.5rem;
      text-align: left;
    }
    .output-file-content table th {
      background: var(--bg);
      font-weight: 600;
    }
    .output-file-content .download-link {
      display: inline-flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.5rem 1rem;
      background: var(--bg);
      border: 1px solid var(--border);
      border-radius: 4px;
      color: var(--accent);
      text-decoration: none;
      font-size: 0.875rem;
      cursor: pointer;
    }
    .output-file-content .download-link:hover {
      background: var(--border);
    }
    .empty-state {
      color: var(--text-muted);
      font-style: italic;
      padding: 2rem;
      text-align: center;
    }

    /* ---- Feedback ---- */
    .prev-feedback {
      background: var(--bg);
      border: 1px solid var(--border);
      border-radius: 4px;
      padding: 0.625rem 0.75rem;
      margin-top: 0.75rem;
      font-size: 0.8125rem;
      color: var(--text-muted);
      line-height: 1.5;
    }
    .prev-feedback-label {
      font-size: 0.7rem;
      font-weight: 600;
      text-transform: uppercase;
      letter-spacing: 0.04em;
      margin-bottom: 0.25rem;
      color: var(--text-muted);
    }
    .feedback-textarea {
      width: 100%;
      min-height: 100px;
      padding: 0.75rem;
      border: 1px solid var(--border);
      border-radius: 4px;
      font-family: inherit;
      font-size: 0.9375rem;
      line-height: 1.5;
      resize: vertical;
      color: var(--text);
    }
    .feedback-textarea:focus {
      outline: none;
      border-color: var(--accent);
      box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.1);
    }
    .feedback-status {
      font-size: 0.75rem;
      color: var(--text-muted);
      margin-top: 0.5rem;
      min-height: 1.1em;
    }

    /* ---- Grades (collapsible) ---- */
    .grades-toggle {
      display: flex;
      align-items: center;
      cursor: pointer;
      user-select: none;
    }
    .grades-toggle:hover {
      color: var(--accent);
    }
    .grades-toggle .arrow {
      margin-right: 0.5rem;
      transition: transform 0.15s;
      font-size: 0.75rem;
    }
    .grades-toggle .arrow.open {
      transform: rotate(90deg);
    }
    .grades-content {
      display: none;
      margin-top: 0.75rem;
    }
    .grades-content.open {
      display: block;
    }
    .grades-summary {
      font-size: 0.875rem;
      margin-bottom: 0.75rem;
      display: flex;
      align-items: center;
      gap: 0.5rem;
    }
    .grade-badge {
      display: inline-block;
      padding: 0.125rem 0.5rem;
      border-radius: 9999px;
      font-size: 0.75rem;
      font-weight: 600;
    }
    .grade-pass { background: var(--green-bg); color: var(--green); }
    .grade-fail { background: var(--red-bg); color: var(--red); }
    .assertion-list {
      list-style: none;
    }
    .assertion-item {
      padding: 0.625rem 0;
      border-bottom: 1px solid var(--border);
      font-size: 0.8125rem;
    }
    .assertion-item:last-child { border-bottom: none; }
    .assertion-status {
      font-weight: 600;
      margin-right: 0.5rem;
    }
    .assertion-status.pass { color: var(--green); }
    .assertion-status.fail { color: var(--red); }
    .assertion-evidence {
      color: var(--text-muted);
      font-size: 0.75rem;
      margin-top: 0.25rem;
      padding-left: 1.5rem;
    }

    /* ---- View tabs ---- */
    .view-tabs {
      display: flex;
      gap: 0;
      padding: 0 2rem;
      background: var(--bg);
      border-bottom: 1px solid var(--border);
      flex-shrink: 0;
    }
    .view-tab {
      font-family: 'Poppins', sans-serif;
      padding: 0.625rem 1.25rem;
      font-size: 0.8125rem;
      font-weight: 500;
      cursor: pointer;
      border: none;
      background: none;
      color: var(--text-muted);
      border-bottom: 2px solid transparent;
      transition: all 0.15s;
    }
    .view-tab:hover { color: var(--text); }
    .view-tab.active {
      color: var(--accent);
      border-bottom-color: var(--accent);
    }
    .view-panel { display: none; }
    .view-panel.active { display: flex; flex-direction: column; flex: 1; overflow: hidden; }

    /* ---- Benchmark view ---- */
    .benchmark-view {
      padding: 1.5rem 2rem;
      overflow-y: auto;
      flex: 1;
    }
    .benchmark-table {
      border-collapse: collapse;
      background: var(--surface);
      border: 1px solid var(--border);
      border-radius: var(--radius);
      font-size: 0.8125rem;
      width: 100%;
      margin-bottom: 1.5rem;
    }
    .benchmark-table th, .benchmark-table td {
      padding: 0.625rem 0.75rem;
      text-align: left;
      border: 1px solid var(--border);
    }
    .benchmark-table th {
      font-family: 'Poppins', sans-serif;
      background: var(--header-bg);
      color: var(--header-text);
      font-weight: 500;
      font-size: 0.75rem;
      text-transform: uppercase;
      letter-spacing: 0.04em;
    }
    .benchmark-table tr:hover { background: var(--bg); }
    .benchmark-table tr.benchmark-row-with { background: rgba(33, 150, 243, 0.06); }
    .benchmark-table tr.benchmark-row-without { background: rgba(255, 193, 7, 0.06); }
    .benchmark-table tr.benchmark-row-with:hover { background: rgba(33, 150, 243, 0.12); }
    .benchmark-table tr.benchmark-row-without:hover { background: rgba(255, 193, 7, 0.12); }
    .benchmark-table tr.benchmark-row-avg { font-weight: 600; border-top: 2px solid var(--border); }
    .benchmark-table tr.benchmark-row-avg.benchmark-row-with { background: rgba(33, 150, 243, 0.12); }
    .benchmark-table tr.benchmark-row-avg.benchmark-row-without { background: rgba(255, 193, 7, 0.12); }
    .benchmark-delta-positive { color: var(--green); font-weight: 600; }
    .benchmark-delta-negative { color: var(--red); font-weight: 600; }
    .benchmark-notes {
      background: var(--surface);
      border: 1px solid var(--border);
      border-radius: var(--radius);
      padding: 1rem;
    }
    .benchmark-notes h3 {
      font-family: 'Poppins', sans-serif;
      font-size: 0.875rem;
      margin-bottom: 0.75rem;
    }
    .benchmark-notes ul {
      list-style: disc;
      padding-left: 1.25rem;
    }
    .benchmark-notes li {
      font-size: 0.8125rem;
      line-height: 1.6;
      margin-bottom: 0.375rem;
    }
    .benchmark-empty {
      color: var(--text-muted);
      font-style: italic;
      text-align: center;
      padding: 3rem;
    }

    /* ---- Navigation ---- */
    .nav {
      display: flex;
      justify-content: space-between;
      align-items: center;
      padding: 1rem 2rem;
      border-top: 1px solid var(--border);
      background: var(--surface);
      flex-shrink: 0;
    }
    .nav-btn {
      font-family: 'Poppins', sans-serif;
      padding: 0.5rem 1.25rem;
      border: 1px solid var(--border);
      border-radius: var(--radius);
      background: var(--surface);
      cursor: pointer;
      font-size: 0.875rem;
      font-weight: 500;
      color: var(--text);
      transition: all 0.15s;
    }
    .nav-btn:hover:not(:disabled) {
      background: var(--bg);
      border-color: var(--text-muted);
    }
    .nav-btn:disabled {
      opacity: 0.4;
      cursor: not-allowed;
    }
    .done-btn {
      font-family: 'Poppins', sans-serif;
      padding: 0.5rem 1.5rem;
      border: 1px solid var(--border);
      border-radius: var(--radius);
      background: var(--surface);
      color: var(--text);
      cursor: pointer;
      font-size: 0.875rem;
      font-weight: 500;
      transition: all 0.15s;
    }
    .done-btn:hover {
      background: var(--bg);
      border-color: var(--text-muted);
    }
    .done-btn.ready {
      border: none;
      background: var(--accent);
      color: white;
      font-weight: 600;
    }
    .done-btn.ready:hover {
      background: var(--accent-hover);
    }
    /* ---- Done overlay ---- */
    .done-overlay {
      display: none;
      position: fixed;
      inset: 0;
      background: rgba(0, 0, 0, 0.5);
      z-index: 100;
      justify-content: center;
      align-items: center;
    }
    .done-overlay.visible {
      display: flex;
    }
    .done-card {
      background: var(--surface);
      border-radius: 12px;
      padding: 2rem 3rem;
      text-align: center;
      box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
      max-width: 500px;
    }
    .done-card h2 {
      font-size: 1.5rem;
      margin-bottom: 0.5rem;
    }
    .done-card p {
      color: var(--text-muted);
      margin-bottom: 1.5rem;
      line-height: 1.5;
    }
    .done-card .btn-row {
      display: flex;
      gap: 0.5rem;
      justify-content: center;
    }
    .done-card button {
      padding: 0.5rem 1.25rem;
      border: 1px solid var(--border);
      border-radius: var(--radius);
      background: var(--surface);
      cursor: pointer;
      font-size: 0.875rem;
    }
    .done-card button:hover {
      background: var(--bg);
    }
    /* ---- Toast ---- */
    .toast {
      position: fixed;
      bottom: 5rem;
      left: 50%;
      transform: translateX(-50%);
      background: var(--header-bg);
      color: var(--header-text);
      padding: 0.625rem 1.25rem;
      border-radius: var(--radius);
      font-size: 0.875rem;
      opacity: 0;
      transition: opacity 0.3s;
      pointer-events: none;
      z-index: 200;
    }
    .toast.visible {
      opacity: 1;
    }
  </style>
</head>
<body>
  <div id="app" style="height:100vh; display:flex; flex-direction:column;">
    <div class="header">
      <div>
        <h1>Eval Review: <span id="skill-name"></span></h1>
        <div class="instructions">Review each output and leave feedback below. Navigate with arrow keys or buttons. When done, copy feedback and paste into Claude Code.</div>
      </div>
      <div class="progress" id="progress"></div>
    </div>

    <!-- View tabs (only shown when benchmark data exists) -->
    <div class="view-tabs" id="view-tabs" style="display:none;">
      <button class="view-tab active" onclick="switchView('outputs')">Outputs</button>
      <button class="view-tab" onclick="switchView('benchmark')">Benchmark</button>
    </div>

    <!-- Outputs panel (qualitative review) -->
    <div class="view-panel active" id="panel-outputs">
    <div class="main">
      <!-- Prompt -->
      <div class="section">
        <div class="section-header">Prompt <span class="config-badge" id="config-badge" style="display:none;"></span></div>
        <div class="section-body">
          <div class="prompt-text" id="prompt-text"></div>
        </div>
      </div>

      <!-- Outputs -->
      <div class="section">
        <div class="section-header">Output</div>
        <div class="section-body" id="outputs-body">
          <div class="empty-state">No output files found</div>
        </div>
      </div>

      <!-- Previous Output (collapsible) -->
      <div class="section" id="prev-outputs-section" style="display:none;">
        <div class="section-header">
          <div class="grades-toggle" onclick="togglePrevOutputs()">
            <span class="arrow" id="prev-outputs-arrow">&#9654;</span>
            Previous Output
          </div>
        </div>
        <div class="grades-content" id="prev-outputs-content"></div>
      </div>

      <!-- Grades (collapsible) -->
      <div class="section" id="grades-section" style="display:none;">
        <div class="section-header">
          <div class="grades-toggle" onclick="toggleGrades()">
            <span class="arrow" id="grades-arrow">&#9654;</span>
            Formal Grades
          </div>
        </div>
        <div class="grades-content" id="grades-content"></div>
      </div>

      <!-- Feedback -->
      <div class="section">
        <div class="section-header">Your Feedback</div>
        <div class="section-body">
          <textarea
            class="feedback-textarea"
            id="feedback"
            placeholder="What do you think of this output? Any issues, suggestions, or things that look great?"
          ></textarea>
          <div class="feedback-status" id="feedback-status"></div>
          <div class="prev-feedback" id="prev-feedback" style="display:none;">
            <div class="prev-feedback-label">Previous feedback</div>
            <div id="prev-feedback-text"></div>
          </div>
        </div>
      </div>
    </div>

    <div class="nav" id="outputs-nav">
      <button class="nav-btn" id="prev-btn" onclick="navigate(-1)">&#8592; Previous</button>
      <button class="done-btn" id="done-btn" onclick="showDoneDialog()">Submit All Reviews</button>
      <button class="nav-btn" id="next-btn" onclick="navigate(1)">Next &#8594;</button>
    </div>
    </div><!-- end panel-outputs -->

    <!-- Benchmark panel (quantitative stats) -->
    <div class="view-panel" id="panel-benchmark">
      <div class="benchmark-view" id="benchmark-content">
        <div class="benchmark-empty">No benchmark data available. Run a benchmark to see quantitative results here.</div>
      </div>
    </div>
  </div>

  <!-- Done overlay -->
  <div class="done-overlay" id="done-overlay">
    <div class="done-card">
      <h2>Review Complete</h2>
      <p>Your feedback has been saved. Go back to your Claude Code session and tell Claude you're done reviewing.</p>
      <div class="btn-row">
        <button onclick="closeDoneDialog()">OK</button>
      </div>
    </div>
  </div>

  <!-- Toast -->
  <div class="toast" id="toast"></div>

  <script>
    // ---- Embedded data (injected by generate_review.py) ----
    /*__EMBEDDED_DATA__*/

    // ---- State ----
    let feedbackMap = {};  // run_id -> feedback text
    let currentIndex = 0;
    let visitedRuns = new Set();

    // ---- Init ----
    async function init() {
      // Load saved feedback from server — but only if this isn't a fresh
      // iteration (indicated by previous_feedback being present). When
      // previous feedback exists, the feedback.json on disk is stale from
      // the prior iteration and should not pre-fill the textareas.
      const hasPrevious = Object.keys(EMBEDDED_DATA.previous_feedback || {}).length > 0
        || Object.keys(EMBEDDED_DATA.previous_outputs || {}).length > 0;
      if (!hasPrevious) {
        try {
          const resp = await fetch("/api/feedback");
          const data = await resp.json();
          if (data.reviews) {
            for (const r of data.reviews) feedbackMap[r.run_id] = r.feedback;
          }
        } catch { /* first run, no feedback yet */ }
      }

      document.getElementById("skill-name").textContent = EMBEDDED_DATA.skill_name;
      showRun(0);

      // Wire up feedback auto-save
      const textarea = document.getElementById("feedback");
      let saveTimeout = null;
      textarea.addEventListener("input", () => {
        clearTimeout(saveTimeout);
        document.getElementById("feedback-status").textContent = "";
        saveTimeout = setTimeout(() => saveCurrentFeedback(), 800);
      });
    }

    // ---- Navigation ----
    function navigate(delta) {
      const newIndex = currentIndex + delta;
      if (newIndex >= 0 && newIndex < EMBEDDED_DATA.runs.length) {
        saveCurrentFeedback();
        showRun(newIndex);
      }
    }

    function updateNavButtons() {
      document.getElementById("prev-btn").disabled = currentIndex === 0;
      document.getElementById("next-btn").disabled =
        currentIndex === EMBEDDED_DATA.runs.length - 1;
    }

    // ---- Show a run ----
    function showRun(index) {
      currentIndex = index;
      const run = EMBEDDED_DATA.runs[index];

      // Progress
      document.getElementById("progress").textContent =
        `index + 1 of EMBEDDED_DATA.runs.length`;

      // Prompt
      document.getElementById("prompt-text").textContent = run.prompt;

      // Config badge
      const badge = document.getElementById("config-badge");
      const configMatch = run.id.match(/(with_skill|without_skill|new_skill|old_skill)/);
      if (configMatch) {
        const config = configMatch[1];
        const isBaseline = config === "without_skill" || config === "old_skill";
        badge.textContent = config.replace(/_/g, " ");
        badge.className = "config-badge " + (isBaseline ? "config-baseline" : "config-primary");
        badge.style.display = "inline-block";
      } else {
        badge.style.display = "none";
      }

      // Outputs
      renderOutputs(run);

      // Previous outputs
      renderPrevOutputs(run);

      // Grades
      renderGrades(run);

      // Previous feedback
      const prevFb = (EMBEDDED_DATA.previous_feedback || {})[run.id];
      const prevEl = document.getElementById("prev-feedback");
      if (prevFb) {
        document.getElementById("prev-feedback-text").textContent = prevFb;
        prevEl.style.display = "block";
      } else {
        prevEl.style.display = "none";
      }

      // Feedback
      document.getElementById("feedback").value = feedbackMap[run.id] || "";
      document.getElementById("feedback-status").textContent = "";

      updateNavButtons();

      // Track visited runs and promote done button when all visited
      visitedRuns.add(index);
      const doneBtn = document.getElementById("done-btn");
      if (visitedRuns.size >= EMBEDDED_DATA.runs.length) {
        doneBtn.classList.add("ready");
      }

      // Scroll main content to top
      document.querySelector(".main").scrollTop = 0;
    }

    // ---- Render outputs ----
    function renderOutputs(run) {
      const container = document.getElementById("outputs-body");
      container.innerHTML = "";

      const outputs = run.outputs || [];
      if (outputs.length === 0) {
        container.innerHTML = '<div class="empty-state">No output files</div>';
        return;
      }

      for (const file of outputs) {
        const fileDiv = document.createElement("div");
        fileDiv.className = "output-file";

        // Always show file header with download link
        const header = document.createElement("div");
        header.className = "output-file-header";
        const nameSpan = document.createElement("span");
        nameSpan.textContent = file.name;
        header.appendChild(nameSpan);
        const dlBtn = document.createElement("a");
        dlBtn.className = "dl-btn";
        dlBtn.textContent = "Download";
        dlBtn.download = file.name;
        dlBtn.href = getDownloadUri(file);
        header.appendChild(dlBtn);
        fileDiv.appendChild(header);

        const content = document.createElement("div");
        content.className = "output-file-content";

        if (file.type === "text") {
          const pre = document.createElement("pre");
          pre.textContent = file.content;
          content.appendChild(pre);
        } else if (file.type === "image") {
          const img = document.createElement("img");
          img.src = file.data_uri;
          img.alt = file.name;
          content.appendChild(img);
        } else if (file.type === "pdf") {
          const iframe = document.createElement("iframe");
          iframe.src = file.data_uri;
          content.appendChild(iframe);
        } else if (file.type === "xlsx") {
          renderXlsx(content, file.data_b64);
        } else if (file.type === "binary") {
          const a = document.createElement("a");
          a.className = "download-link";
          a.href = file.data_uri;
          a.download = file.name;
          a.textContent = "Download " + file.name;
          content.appendChild(a);
        } else if (file.type === "error") {
          const pre = document.createElement("pre");
          pre.textContent = file.content;
          pre.style.color = "var(--red)";
          content.appendChild(pre);
        }

        fileDiv.appendChild(content);
        container.appendChild(fileDiv);
      }
    }

    // ---- XLSX rendering via SheetJS ----
    function renderXlsx(container, b64Data) {
      try {
        const raw = Uint8Array.from(atob(b64Data), c => c.charCodeAt(0));
        const wb = XLSX.read(raw, { type: "array" });

        for (let i = 0; i < wb.SheetNames.length; i++) {
          const sheetName = wb.SheetNames[i];
          const ws = wb.Sheets[sheetName];

          if (wb.SheetNames.length > 1) {
            const sheetLabel = document.createElement("div");
            sheetLabel.style.cssText =
              "font-weight:600; font-size:0.8rem; color:#b0aea5; margin-top:0.5rem; margin-bottom:0.25rem;";
            sheetLabel.textContent = "Sheet: " + sheetName;
            container.appendChild(sheetLabel);
          }

          const htmlStr = XLSX.utils.sheet_to_html(ws, { editable: false });
          const wrapper = document.createElement("div");
          wrapper.innerHTML = htmlStr;
          container.appendChild(wrapper);
        }
      } catch (err) {
        container.textContent = "Error rendering spreadsheet: " + err.message;
      }
    }

    // ---- Grades ----
    function renderGrades(run) {
      const section = document.getElementById("grades-section");
      const content = document.getElementById("grades-content");

      if (!run.grading) {
        section.style.display = "none";
        return;
      }

      const grading = run.grading;
      section.style.display = "block";
      // Reset to collapsed
      content.classList.remove("open");
      document.getElementById("grades-arrow").classList.remove("open");

      const summary = grading.summary || {};
      const expectations = grading.expectations || [];

      let html = '<div style="padding: 1rem;">';

      // Summary line
      const passRate = summary.pass_rate != null
        ? Math.round(summary.pass_rate * 100) + "%"
        : "?";
      const badgeClass = summary.pass_rate >= 0.8 ? "grade-pass" : summary.pass_rate >= 0.5 ? "" : "grade-fail";
      html += '<div class="grades-summary">';
      html += '<span class="grade-badge ' + badgeClass + '">' + passRate + '</span>';
      html += '<span>' + (summary.passed || 0) + ' passed, ' + (summary.failed || 0) + ' failed of ' + (summary.total || 0) + '</span>';
      html += '</div>';

      // Assertions list
      html += '<ul class="assertion-list">';
      for (const exp of expectations) {
        const statusClass = exp.passed ? "pass" : "fail";
        const statusIcon = exp.passed ? "\u2713" : "\u2717";
        html += '<li class="assertion-item">';
        html += '<span class="assertion-status ' + statusClass + '">' + statusIcon + '</span>';
        html += '<span>' + escapeHtml(exp.text) + '</span>';
        if (exp.evidence) {
          html += '<div class="assertion-evidence">' + escapeHtml(exp.evidence) + '</div>';
        }
        html += '</li>';
      }
      html += '</ul>';

      html += '</div>';
      content.innerHTML = html;
    }

    function toggleGrades() {
      const content = document.getElementById("grades-content");
      const arrow = document.getElementById("grades-arrow");
      content.classList.toggle("open");
      arrow.classList.toggle("open");
    }

    // ---- Previous outputs (collapsible) ----
    function renderPrevOutputs(run) {
      const section = document.getElementById("prev-outputs-section");
      const content = document.getElementById("prev-outputs-content");
      const prevOutputs = (EMBEDDED_DATA.previous_outputs || {})[run.id];

      if (!prevOutputs || prevOutputs.length === 0) {
        section.style.display = "none";
        return;
      }

      section.style.display = "block";
      // Reset to collapsed
      content.classList.remove("open");
      document.getElementById("prev-outputs-arrow").classList.remove("open");

      // Render the files into the content area
      content.innerHTML = "";
      const wrapper = document.createElement("div");
      wrapper.style.padding = "1rem";

      for (const file of prevOutputs) {
        const fileDiv = document.createElement("div");
        fileDiv.className = "output-file";

        const header = document.createElement("div");
        header.className = "output-file-header";
        const nameSpan = document.createElement("span");
        nameSpan.textContent = file.name;
        header.appendChild(nameSpan);
        const dlBtn = document.createElement("a");
        dlBtn.className = "dl-btn";
        dlBtn.textContent = "Download";
        dlBtn.download = file.name;
        dlBtn.href = getDownloadUri(file);
        header.appendChild(dlBtn);
        fileDiv.appendChild(header);

        const fc = document.createElement("div");
        fc.className = "output-file-content";

        if (file.type === "text") {
          const pre = document.createElement("pre");
          pre.textContent = file.content;
          fc.appendChild(pre);
        } else if (file.type === "image") {
          const img = document.createElement("img");
          img.src = file.data_uri;
          img.alt = file.name;
          fc.appendChild(img);
        } else if (file.type === "pdf") {
          const iframe = document.createElement("iframe");
          iframe.src = file.data_uri;
          fc.appendChild(iframe);
        } else if (file.type === "xlsx") {
          renderXlsx(fc, file.data_b64);
        } else if (file.type === "binary") {
          const a = document.createElement("a");
          a.className = "download-link";
          a.href = file.data_uri;
          a.download = file.name;
          a.textContent = "Download " + file.name;
          fc.appendChild(a);
        }

        fileDiv.appendChild(fc);
        wrapper.appendChild(fileDiv);
      }

      content.appendChild(wrapper);
    }

    function togglePrevOutputs() {
      const content = document.getElementById("prev-outputs-content");
      const arrow = document.getElementById("prev-outputs-arrow");
      content.classList.toggle("open");
      arrow.classList.toggle("open");
    }

    // ---- Feedback (saved to server -> feedback.json) ----
    function saveCurrentFeedback() {
      const run = EMBEDDED_DATA.runs[currentIndex];
      const text = document.getElementById("feedback").value;

      if (text.trim() === "") {
        delete feedbackMap[run.id];
      } else {
        feedbackMap[run.id] = text;
      }

      // Build reviews array from map
      const reviews = [];
      for (const [run_id, feedback] of Object.entries(feedbackMap)) {
        if (feedback.trim()) {
          reviews.push({ run_id, feedback, timestamp: new Date().toISOString() });
        }
      }

      fetch("/api/feedback", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ reviews, status: "in_progress" }),
      }).then(() => {
        document.getElementById("feedback-status").textContent = "Saved";
      }).catch(() => {
        // Static mode or server unavailable — no-op on auto-save,
        // feedback will be downloaded on final submit
        document.getElementById("feedback-status").textContent = "Will download on submit";
      });
    }

    // ---- Done ----
    function showDoneDialog() {
      // Save current textarea to feedbackMap (but don't POST yet)
      const run = EMBEDDED_DATA.runs[currentIndex];
      const text = document.getElementById("feedback").value;
      if (text.trim() === "") {
        delete feedbackMap[run.id];
      } else {
        feedbackMap[run.id] = text;
      }

      // POST once with status: complete — include ALL runs so the model
      // can distinguish "no feedback" (looks good) from "not reviewed"
      const reviews = [];
      const ts = new Date().toISOString();
      for (const r of EMBEDDED_DATA.runs) {
        reviews.push({ run_id: r.id, feedback: feedbackMap[r.id] || "", timestamp: ts });
      }
      const payload = JSON.stringify({ reviews, status: "complete" }, null, 2);
      fetch("/api/feedback", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: payload,
      }).then(() => {
        document.getElementById("done-overlay").classList.add("visible");
      }).catch(() => {
        // Server not available (static mode) — download as file
        const blob = new Blob([payload], { type: "application/json" });
        const url = URL.createObjectURL(blob);
        const a = document.createElement("a");
        a.href = url;
        a.download = "feedback.json";
        a.click();
        URL.revokeObjectURL(url);
        document.getElementById("done-overlay").classList.add("visible");
      });
    }

    function closeDoneDialog() {
      // Reset status back to in_progress
      saveCurrentFeedback();
      document.getElementById("done-overlay").classList.remove("visible");
    }

    // ---- Toast ----
    function showToast(message) {
      const toast = document.getElementById("toast");
      toast.textContent = message;
      toast.classList.add("visible");
      setTimeout(() => toast.classList.remove("visible"), 2000);
    }

    // ---- Keyboard nav ----
    document.addEventListener("keydown", (e) => {
      // Don't capture when typing in textarea
      if (e.target.tagName === "TEXTAREA") return;

      if (e.key === "ArrowLeft" || e.key === "ArrowUp") {
        e.preventDefault();
        navigate(-1);
      } else if (e.key === "ArrowRight" || e.key === "ArrowDown") {
        e.preventDefault();
        navigate(1);
      }
    });

    // ---- Util ----
    function getDownloadUri(file) {
      if (file.data_uri) return file.data_uri;
      if (file.data_b64) return "data:application/octet-stream;base64," + file.data_b64;
      if (file.type === "text") return "data:text/plain;charset=utf-8," + encodeURIComponent(file.content);
      return "#";
    }

    function escapeHtml(text) {
      const div = document.createElement("div");
      div.textContent = text;
      return div.innerHTML;
    }

    // ---- View switching ----
    function switchView(view) {
      document.querySelectorAll(".view-tab").forEach(t => t.classList.remove("active"));
      document.querySelectorAll(".view-panel").forEach(p => p.classList.remove("active"));
      document.querySelector(`[onclick="switchView('view')"]`).classList.add("active");
      document.getElementById("panel-" + view).classList.add("active");
    }

    // ---- Benchmark rendering ----
    function renderBenchmark() {
      const data = EMBEDDED_DATA.benchmark;
      if (!data) return;

      // Show the tabs
      document.getElementById("view-tabs").style.display = "flex";

      const container = document.getElementById("benchmark-content");
      const summary = data.run_summary || {};
      const metadata = data.metadata || {};
      const notes = data.notes || [];

      let html = "";

      // Header
      html += "<h2 style='font-family: Poppins, sans-serif; margin-bottom: 0.5rem;'>Benchmark Results</h2>";
      html += "<p style='color: var(--text-muted); font-size: 0.875rem; margin-bottom: 1.25rem;'>";
      if (metadata.skill_name) html += "<strong>" + escapeHtml(metadata.skill_name) + "</strong> &mdash; ";
      if (metadata.timestamp) html += metadata.timestamp + " &mdash; ";
      if (metadata.evals_run) html += "Evals: " + metadata.evals_run.join(", ") + " &mdash; ";
      html += (metadata.runs_per_configuration || "?") + " runs per configuration";
      html += "</p>";

      // Summary table
      html += '<table class="benchmark-table">';

      function fmtStat(stat, pct) {
        if (!stat) return "—";
        const suffix = pct ? "%" : "";
        const m = pct ? (stat.mean * 100).toFixed(0) : stat.mean.toFixed(1);
        const s = pct ? (stat.stddev * 100).toFixed(0) : stat.stddev.toFixed(1);
        return m + suffix + " ± " + s + suffix;
      }

      function deltaClass(val) {
        if (!val) return "";
        const n = parseFloat(val);
        if (n > 0) return "benchmark-delta-positive";
        if (n < 0) return "benchmark-delta-negative";
        return "";
      }

      // Discover config names dynamically (everything except "delta")
      const configs = Object.keys(summary).filter(k => k !== "delta");
      const configA = configs[0] || "config_a";
      const configB = configs[1] || "config_b";
      const labelA = configA.replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase());
      const labelB = configB.replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase());
      const a = summary[configA] || {};
      const b = summary[configB] || {};
      const delta = summary.delta || {};

      html += "<thead><tr><th>Metric</th><th>" + escapeHtml(labelA) + "</th><th>" + escapeHtml(labelB) + "</th><th>Delta</th></tr></thead>";
      html += "<tbody>";

      html += "<tr><td><strong>Pass Rate</strong></td>";
      html += "<td>" + fmtStat(a.pass_rate, true) + "</td>";
      html += "<td>" + fmtStat(b.pass_rate, true) + "</td>";
      html += '<td class="' + deltaClass(delta.pass_rate) + '">' + (delta.pass_rate || "—") + "</td></tr>";

      // Time (only show row if data exists)
      if (a.time_seconds || b.time_seconds) {
        html += "<tr><td><strong>Time (s)</strong></td>";
        html += "<td>" + fmtStat(a.time_seconds, false) + "</td>";
        html += "<td>" + fmtStat(b.time_seconds, false) + "</td>";
        html += '<td class="' + deltaClass(delta.time_seconds) + '">' + (delta.time_seconds ? delta.time_seconds + "s" : "—") + "</td></tr>";
      }

      // Tokens (only show row if data exists)
      if (a.tokens || b.tokens) {
        html += "<tr><td><strong>Tokens</strong></td>";
        html += "<td>" + fmtStat(a.tokens, false) + "</td>";
        html += "<td>" + fmtStat(b.tokens, false) + "</td>";
        html += '<td class="' + deltaClass(delta.tokens) + '">' + (delta.tokens || "—") + "</td></tr>";
      }

      html += "</tbody></table>";

      // Per-eval breakdown (if runs data available)
      const runs = data.runs || [];
      if (runs.length > 0) {
        const evalIds = [...new Set(runs.map(r => r.eval_id))].sort((a, b) => a - b);

        html += "<h3 style='font-family: Poppins, sans-serif; margin-bottom: 0.75rem;'>Per-Eval Breakdown</h3>";

        const hasTime = runs.some(r => r.result && r.result.time_seconds != null);
        const hasErrors = runs.some(r => r.result && r.result.errors > 0);

        for (const evalId of evalIds) {
          const evalRuns = runs.filter(r => r.eval_id === evalId);
          const evalName = evalRuns[0] && evalRuns[0].eval_name ? evalRuns[0].eval_name : "Eval " + evalId;

          html += "<h4 style='font-family: Poppins, sans-serif; margin: 1rem 0 0.5rem; color: var(--text);'>" + escapeHtml(evalName) + "</h4>";
          html += '<table class="benchmark-table">';
          html += "<thead><tr><th>Config</th><th>Run</th><th>Pass Rate</th>";
          if (hasTime) html += "<th>Time (s)</th>";
          if (hasErrors) html += "<th>Crashes During Execution</th>";
          html += "</tr></thead>";
          html += "<tbody>";

          // Group by config and render with average rows
          const configGroups = [...new Set(evalRuns.map(r => r.configuration))];
          for (let ci = 0; ci < configGroups.length; ci++) {
            const config = configGroups[ci];
            const configRuns = evalRuns.filter(r => r.configuration === config);
            if (configRuns.length === 0) continue;

            const rowClass = ci === 0 ? "benchmark-row-with" : "benchmark-row-without";
            const configLabel = config.replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase());

            for (const run of configRuns) {
              const r = run.result || {};
              const prClass = r.pass_rate >= 0.8 ? "benchmark-delta-positive" : r.pass_rate < 0.5 ? "benchmark-delta-negative" : "";
              html += '<tr class="' + rowClass + '">';
              html += "<td>" + configLabel + "</td>";
              html += "<td>" + run.run_number + "</td>";
              html += '<td class="' + prClass + '">' + ((r.pass_rate || 0) * 100).toFixed(0) + "% (" + (r.passed || 0) + "/" + (r.total || 0) + ")</td>";
              if (hasTime) html += "<td>" + (r.time_seconds != null ? r.time_seconds.toFixed(1) : "—") + "</td>";
              if (hasErrors) html += "<td>" + (r.errors || 0) + "</td>";
              html += "</tr>";
            }

            // Average row
            const rates = configRuns.map(r => (r.result || {}).pass_rate || 0);
            const avgRate = rates.reduce((a, b) => a + b, 0) / rates.length;
            const avgPrClass = avgRate >= 0.8 ? "benchmark-delta-positive" : avgRate < 0.5 ? "benchmark-delta-negative" : "";
            html += '<tr class="benchmark-row-avg ' + rowClass + '">';
            html += "<td>" + configLabel + "</td>";
            html += "<td>Avg</td>";
            html += '<td class="' + avgPrClass + '">' + (avgRate * 100).toFixed(0) + "%</td>";
            if (hasTime) {
              const times = configRuns.map(r => (r.result || {}).time_seconds).filter(t => t != null);
              html += "<td>" + (times.length ? (times.reduce((a, b) => a + b, 0) / times.length).toFixed(1) : "—") + "</td>";
            }
            if (hasErrors) html += "<td></td>";
            html += "</tr>";
          }
          html += "</tbody></table>";

          // Per-assertion detail for this eval
          const runsWithExpectations = {};
          for (const config of configGroups) {
            runsWithExpectations[config] = evalRuns.filter(r => r.configuration === config && r.expectations && r.expectations.length > 0);
          }
          const hasAnyExpectations = Object.values(runsWithExpectations).some(runs => runs.length > 0);
          if (hasAnyExpectations) {
            // Collect all unique assertion texts across all configs
            const allAssertions = [];
            const seen = new Set();
            for (const config of configGroups) {
              for (const run of runsWithExpectations[config]) {
                for (const exp of (run.expectations || [])) {
                  if (!seen.has(exp.text)) {
                    seen.add(exp.text);
                    allAssertions.push(exp.text);
                  }
                }
              }
            }

            html += '<table class="benchmark-table" style="margin-top: 0.5rem;">';
            html += "<thead><tr><th>Assertion</th>";
            for (const config of configGroups) {
              const label = config.replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase());
              html += "<th>" + escapeHtml(label) + "</th>";
            }
            html += "</tr></thead><tbody>";

            for (const assertionText of allAssertions) {
              html += "<tr><td>" + escapeHtml(assertionText) + "</td>";

              for (const config of configGroups) {
                html += "<td>";
                for (const run of runsWithExpectations[config]) {
                  const exp = (run.expectations || []).find(e => e.text === assertionText);
                  if (exp) {
                    const cls = exp.passed ? "benchmark-delta-positive" : "benchmark-delta-negative";
                    const icon = exp.passed ? "\u2713" : "\u2717";
                    html += '<span class="' + cls + '" title="Run ' + run.run_number + ': ' + escapeHtml(exp.evidence || "") + '">' + icon + "</span> ";
                  } else {
                    html += "— ";
                  }
                }
                html += "</td>";
              }
              html += "</tr>";
            }
            html += "</tbody></table>";
          }
        }
      }

      // Notes
      if (notes.length > 0) {
        html += '<div class="benchmark-notes">';
        html += "<h3>Analysis Notes</h3>";
        html += "<ul>";
        for (const note of notes) {
          html += "<li>" + escapeHtml(note) + "</li>";
        }
        html += "</ul></div>";
      }

      container.innerHTML = html;
    }

    // ---- Start ----
    init();
    renderBenchmark();
  </script>
</body>
</html>

FILE:daily-menu/SKILL.md
---
name: daily-menu
description: >-
  生成今日菜单推荐。根据用户手头的食材、口味偏好、人数和烹饪时间，
  从内置食材库和菜谱库中智能匹配，输出完整的菜单方案和分步烹饪指南。
  当用户提到"今天吃什么""做什么菜""菜单""菜谱推荐""晚饭吃啥"等意图时触发。
---

# 今日菜单生成器

根据用户现有食材、口味偏好、就餐人数和可用时间，生成个性化菜单推荐和烹饪指南。

## 工作流程

### 第一步：了解用户需求

通过简短对话收集以下信息（缺失项用合理默认值）：

| 信息项 | 默认值 | 说明 |
|--------|--------|------|
| 手头食材 | — | **必问**，至少确认 1~3 种主要食材 |
| 就餐人数 | 2 人 | 影响份量建议 |
| 口味偏好 | 家常 | 家常 / 清淡减脂 / 川湘重口 / 快手10分钟 |
| 可用时间 | 60 分钟 | 影响菜品复杂度 |
| 忌口/过敏 | 无 | 如有则排除相关食材 |
| 菜品数量 | 2~4 道 | 根据人数自动建议 |

**对话原则：**
- 不要一次问太多问题，最核心的是「你手头有什么食材？」
- 如果用户只说了食材，其他用默认值直接推荐
- 语气轻松友好，像朋友聊天一样

### 第二步：匹配菜谱

1. 读取 `references/ingredients.md` 获取完整食材分类
2. 读取 `references/recipes.md` 获取菜谱库
3. 根据用户提供的食材，从菜谱库中匹配可做的菜品
4. 考虑荤素搭配、营养均衡、烹饪难度

**匹配规则：**
- 主料必须匹配（用户手头有的食材）
- 常见调料（盐、酱油、醋、糖、料酒、蚝油等）默认家里有，不需要确认
- 优先推荐主料完全匹配的菜，其次推荐只差 1~2 种配料的菜
- 如果用户食材能做的菜不够，可以建议额外采购少量食材

### 第三步：输出菜单

使用以下格式输出：

```
## 🍽️ 今日菜单推荐

**就餐人数：** X 人 | **预计用时：** X 分钟 | **风格：** XXX

---

### 1. 菜名 ⭐
> 一句话点评这道菜的特点

**食材：**
- 主料：XXX
- 配料：XXX
- 调料：XXX

**做法：**
1. 第一步（附时间和火候）
2. 第二步
3. ...

**小贴士：** 实用烹饪技巧

---

### 2. 菜名
（同上格式）

---

## 📋 备菜清单

把所有菜需要的食材汇总，方便一次性准备：

| 分类 | 食材 | 用量 | 处理方式 |
|------|------|------|----------|
| 肉类 | ... | ... | ... |
| 蔬菜 | ... | ... | ... |

## ⏱️ 烹饪时间线

建议的做菜顺序和并行操作：
1. 先做 XX（耗时最长的先开始）
2. 在等待的同时准备 XX
3. 最后快炒 XX
```

### 第四步：后续互动

菜单输出后，主动询问：
- 「要不要换掉某道菜？」
- 「要不要看更详细的某道菜做法？」
- 「还想加个汤/凉菜吗？」

## 口味风格指南

### 家常风格（默认）
- 红烧、清炒、炖煮为主
- 调味适中，老少皆宜
- 代表菜：红烧肉、番茄炒蛋、清炒时蔬

### 清淡减脂
- 少油少盐，以蒸、煮、白灼为主
- 多蔬菜，蛋白质优先选鸡胸肉/鱼/虾/豆腐
- 减少碳水，避免油炸
- 标注估算热量

### 快手 10 分钟
- 只推荐炒、拌、煮等快速烹饪方式
- 食材处理简单（切丝切片为主）
- 每道菜控制在 10 分钟以内

### 川湘重口味
- 麻辣鲜香，重油重味
- 豆瓣酱、辣椒、花椒、剁椒等调料
- 代表菜：麻婆豆腐、辣子鸡、酸辣土豆丝

## 重要原则

1. **实用优先**：做法描述要具体到火候、时间、用量，不要含糊
2. **荤素搭配**：2 道菜以上时确保有荤有素
3. **难度递进**：多道菜时从简到难排列
4. **时间合理**：给出的总用时要考虑并行操作
5. **食材不浪费**：尽量用完用户提到的食材
6. **安全第一**：涉及生食（如三文鱼）要提醒新鲜度要求

FILE:daily-menu/scripts/generate_menu.py
#!/usr/bin/env python3
"""
今日菜单生成器 - 根据用户食材自动匹配菜谱并生成菜单方案。

用法:
    python scripts/generate_menu.py --ingredients "鸡翅,土豆,西红柿,鸡蛋"
    python scripts/generate_menu.py --ingredients "五花肉,冬瓜" --people 4 --style 家常
    python scripts/generate_menu.py --ingredients "鸡胸肉,黄瓜,西兰花" --style 清淡减脂
    python scripts/generate_menu.py --ingredients "里脊肉,豆腐" --style 川湘重口 --count 3
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path
from typing import Optional


# ── 菜谱数据 ──────────────────────────────────────────────────────────

RECIPES = [
    {
        "id": 1,
        "name": "红烧肉",
        "main_ingredients": ["五花肉"],
        "styles": ["家常"],
        "difficulty": 2,
        "time_minutes": 50,
        "serves": "2~3人",
    },
    {
        "id": 2,
        "name": "可乐鸡翅",
        "main_ingredients": ["鸡翅"],
        "styles": ["家常"],
        "difficulty": 1,
        "time_minutes": 25,
        "serves": "2人",
    },
    {
        "id": 3,
        "name": "番茄炒蛋",
        "main_ingredients": ["西红柿", "鸡蛋"],
        "styles": ["家常", "快手10分钟"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
    },
    {
        "id": 4,
        "name": "酸辣土豆丝",
        "main_ingredients": ["土豆"],
        "styles": ["家常", "快手10分钟", "川湘重口"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
    },
    {
        "id": 5,
        "name": "蒜蓉西兰花",
        "main_ingredients": ["西兰花"],
        "styles": ["家常", "快手10分钟", "清淡减脂"],
        "difficulty": 1,
        "time_minutes": 8,
        "serves": "2人",
    },
    {
        "id": 6,
        "name": "红烧排骨",
        "main_ingredients": ["排骨"],
        "styles": ["家常"],
        "difficulty": 2,
        "time_minutes": 60,
        "serves": "2~3人",
    },
    {
        "id": 7,
        "name": "麻婆豆腐",
        "main_ingredients": ["豆腐", "猪肉"],
        "styles": ["家常", "川湘重口"],
        "difficulty": 2,
        "time_minutes": 15,
        "serves": "2人",
    },
    {
        "id": 8,
        "name": "清炒空心菜",
        "main_ingredients": ["空心菜"],
        "styles": ["家常", "快手10分钟"],
        "difficulty": 1,
        "time_minutes": 5,
        "serves": "2人",
    },
    {
        "id": 9,
        "name": "清蒸鲈鱼",
        "main_ingredients": ["鲈鱼"],
        "styles": ["家常"],
        "difficulty": 2,
        "time_minutes": 20,
        "serves": "2~3人",
    },
    {
        "id": 10,
        "name": "冬瓜丸子汤",
        "main_ingredients": ["冬瓜", "猪肉"],
        "styles": ["家常"],
        "difficulty": 1,
        "time_minutes": 25,
        "serves": "2~3人",
    },
    {
        "id": 11,
        "name": "蒜蓉炒虾仁",
        "main_ingredients": ["虾"],
        "styles": ["快手10分钟"],
        "difficulty": 1,
        "time_minutes": 8,
        "serves": "2人",
    },
    {
        "id": 12,
        "name": "凉拌黄瓜",
        "main_ingredients": ["黄瓜"],
        "styles": ["快手10分钟"],
        "difficulty": 1,
        "time_minutes": 5,
        "serves": "2人",
    },
    {
        "id": 13,
        "name": "肥牛金针菇卷",
        "main_ingredients": ["肥牛", "金针菇"],
        "styles": ["快手10分钟"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
    },
    {
        "id": 14,
        "name": "西红柿蛋花汤",
        "main_ingredients": ["西红柿", "鸡蛋"],
        "styles": ["快手10分钟", "清淡减脂"],
        "difficulty": 1,
        "time_minutes": 8,
        "serves": "2人",
    },
    {
        "id": 15,
        "name": "白灼虾",
        "main_ingredients": ["虾"],
        "styles": ["清淡减脂"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
        "calories": "~200kcal",
    },
    {
        "id": 16,
        "name": "水煮鸡胸肉沙拉",
        "main_ingredients": ["鸡胸肉"],
        "styles": ["清淡减脂"],
        "difficulty": 1,
        "time_minutes": 15,
        "serves": "1人",
        "calories": "~300kcal",
    },
    {
        "id": 17,
        "name": "清蒸鳕鱼",
        "main_ingredients": ["鳕鱼"],
        "styles": ["清淡减脂"],
        "difficulty": 1,
        "time_minutes": 15,
        "serves": "1人",
        "calories": "~180kcal",
    },
    {
        "id": 18,
        "name": "辣子鸡",
        "main_ingredients": ["鸡腿", "鸡翅", "鸡肉"],
        "styles": ["川湘重口"],
        "difficulty": 2,
        "time_minutes": 25,
        "serves": "2~3人",
    },
    {
        "id": 19,
        "name": "水煮肉片",
        "main_ingredients": ["里脊肉", "猪肉"],
        "styles": ["川湘重口"],
        "difficulty": 2,
        "time_minutes": 20,
        "serves": "2~3人",
    },
    {
        "id": 20,
        "name": "剁椒鱼头",
        "main_ingredients": ["鳙鱼"],
        "styles": ["川湘重口"],
        "difficulty": 2,
        "time_minutes": 25,
        "serves": "2~3人",
    },
]

# 食材别名映射 → 标准名
ALIASES = {
    "番茄": "西红柿",
    "蕃茄": "西红柿",
    "洋柿子": "西红柿",
    "瘦肉": "猪肉",
    "前腿肉": "猪肉",
    "肉末": "猪肉",
    "肉馅": "猪肉",
    "猪里脊": "里脊肉",
    "小里脊": "里脊肉",
    "肥肠": "猪大肠",
    "猪手": "猪蹄",
    "猪脚": "猪蹄",
    "牛腱": "牛腱子",
    "肥牛卷": "肥牛",
    "肥牛片": "肥牛",
    "琵琶腿": "鸡腿",
    "大鸡腿": "鸡腿",
    "鸡翅中": "鸡翅",
    "翅中": "鸡翅",
    "凤爪": "鸡爪",
    "鸡胸": "鸡胸肉",
    "海鲈鱼": "鲈鱼",
    "基围虾": "虾",
    "大虾": "虾",
    "明虾": "虾",
    "虾仁": "虾",
    "龙虾": "小龙虾",
    "蛤蜊": "花甲",
    "蚬子": "花甲",
    "牡蛎": "生蚝",
    "海蛎子": "生蚝",
    "乌贼": "墨鱼",
    "章鱼": "八爪鱼",
    "小章鱼": "八爪鱼",
    "黄鱼": "黄花鱼",
    "鲑鱼": "三文鱼",
    "胖头鱼": "鳙鱼",
    "花鲢": "鳙鱼",
    "蛋": "鸡蛋",
    "老豆腐": "豆腐",
    "北豆腐": "豆腐",
    "内酯豆腐": "嫩豆腐",
    "南豆腐": "嫩豆腐",
    "豆腐干": "豆干",
    "香干": "豆干",
    "豆皮": "千张",
    "百叶": "千张",
    "大白菜": "白菜",
    "小白菜": "娃娃菜",
    "通菜": "空心菜",
    "蕹菜": "空心菜",
    "西芹": "芹菜",
    "芫荽": "香菜",
    "绿花菜": "西兰花",
    "花菜": "菜花",
    "白花菜": "菜花",
    "青瓜": "黄瓜",
    "凉瓜": "苦瓜",
    "马铃薯": "土豆",
    "淮山": "山药",
    "地瓜": "红薯",
    "番薯": "红薯",
    "红萝卜": "胡萝卜",
    "蒜头": "大蒜",
    "蒜": "大蒜",
    "姜": "生姜",
    "柿子椒": "青椒",
    "彩椒": "红椒",
    "藕": "莲藕",
    "冬菇": "香菇",
    "黑木耳": "木耳",
    "白木耳": "银耳",
    "昆布": "海带",
    "龙口粉丝": "粉丝",
    "红薯粉条": "粉条",
    "金针菜": "黄花菜",
    "白米": "大米",
    "黄小米": "小米",
    "江米": "糯米",
    "挂面": "面条",
    "手擀面": "面条",
    "中筋粉": "面粉",
    "赤小豆": "红豆",
}


def normalize_ingredient(name: str) -> str:
    """将用户输入的食材名标准化。"""
    name = name.strip()
    return ALIASES.get(name, name)


def match_recipes(user_ingredients: list[str], style: str | None = None) -> list[dict]:
    """根据用户食材和风格偏好匹配菜谱。

    返回按匹配度排序的菜谱列表，每个菜谱附带 match_score。
    """
    normalized = [normalize_ingredient(i) for i in user_ingredients]
    results = []

    for recipe in RECIPES:
        # 风格过滤
        if style and style not in recipe["styles"]:
            continue

        # 计算主料匹配度
        required = recipe["main_ingredients"]
        matched = sum(1 for r in required if r in normalized)

        if matched == 0:
            continue

        score = matched / len(required)  # 1.0 = 完全匹配
        missing = [r for r in required if r not in normalized]

        results.append({
            **recipe,
            "match_score": score,
            "missing_ingredients": missing,
        })

    # 按匹配度降序、难度升序排列
    results.sort(key=lambda x: (-x["match_score"], x["difficulty"]))
    return results


def categorize_ingredient(name: str) -> str:
    """判断食材类别。"""
    meat = {"猪肉", "五花肉", "排骨", "猪蹄", "里脊肉", "猪肝", "猪大肠",
            "牛肉", "牛腩", "牛腱子", "肥牛", "羊肉", "羊排",
            "鸡肉", "鸡腿", "鸡翅", "鸡爪", "鸡胸肉", "鸭肉", "鸭翅"}
    seafood = {"草鱼", "鲫鱼", "鲈鱼", "黑鱼", "黄骨鱼", "鲢鱼", "鳙鱼",
               "虾", "小龙虾", "螃蟹", "花甲", "扇贝", "生蚝",
               "鱿鱼", "墨鱼", "八爪鱼", "带鱼", "黄花鱼", "鳕鱼", "三文鱼"}
    egg_tofu = {"鸡蛋", "鸭蛋", "鹅蛋", "鹌鹑蛋",
                "豆腐", "嫩豆腐", "冻豆腐", "豆干", "千张", "腐竹"}
    vegs = {"白菜", "娃娃菜", "菠菜", "生菜", "油麦菜", "空心菜", "韭菜",
            "芹菜", "香菜", "茼蒿", "西兰花", "菜花", "黄瓜", "冬瓜",
            "南瓜", "丝瓜", "苦瓜", "茄子", "西红柿", "土豆", "山药",
            "红薯", "胡萝卜", "白萝卜", "洋葱", "大蒜", "生姜",
            "青椒", "红椒", "莲藕", "金针菇"}
    dried = {"香菇", "木耳", "银耳", "海带", "紫菜", "粉丝", "粉条", "黄花菜", "茶树菇"}
    staple = {"大米", "小米", "糯米", "玉米", "面条", "馒头", "面粉", "绿豆", "红豆", "花生"}

    n = normalize_ingredient(name)
    if n in meat:
        return "肉类"
    if n in seafood:
        return "水产海鲜"
    if n in egg_tofu:
        return "蛋类/豆制品"
    if n in vegs:
        return "蔬菜"
    if n in dried:
        return "干货/菌菇"
    if n in staple:
        return "主食杂粮"
    return "其他"


def generate_menu(
    user_ingredients: list[str],
    people: int = 2,
    style: str | None = None,
    count: int | None = None,
    time_limit: int | None = None,
) -> dict:
    """生成完整菜单方案。

    Args:
        user_ingredients: 用户手头的食材列表
        people: 就餐人数
        style: 口味偏好（家常/清淡减脂/快手10分钟/川湘重口）
        count: 期望菜品数量
        time_limit: 可用烹饪时间（分钟）

    Returns:
        包含推荐菜品、备菜清单、时间线的字典
    """
    if count is None:
        count = min(max(2, people), 4)  # 2~4 道菜

    # 匹配菜谱
    matched = match_recipes(user_ingredients, style)

    if not matched:
        return {
            "success": False,
            "message": "抱歉，根据你提供的食材暂时没有匹配的菜谱。",
            "user_ingredients": user_ingredients,
            "suggestions": "试试提供更多食材，或者换个口味风格？",
        }

    # 选菜策略：荤素搭配
    selected = []
    has_meat = False
    has_veg = False

    for recipe in matched:
        if len(selected) >= count:
            break

        # 时间限制
        if time_limit and recipe["time_minutes"] > time_limit:
            continue

        # 判断荤素
        is_meat = any(
            categorize_ingredient(i) in ("肉类", "水产海鲜")
            for i in recipe["main_ingredients"]
        )

        selected.append({**recipe, "is_meat": is_meat})
        if is_meat:
            has_meat = True
        else:
            has_veg = True

    # 如果只有荤或只有素，且还有余量，补充
    if len(selected) < count and selected:
        for recipe in matched:
            if recipe["id"] in [s["id"] for s in selected]:
                continue
            if len(selected) >= count:
                break

            is_meat = any(
                categorize_ingredient(i) in ("肉类", "水产海鲜")
                for i in recipe["main_ingredients"]
            )

            if (not has_veg and not is_meat) or (not has_meat and is_meat):
                selected.append({**recipe, "is_meat": is_meat})
                if is_meat:
                    has_meat = True
                else:
                    has_veg = True

    # 按耗时从长到短排列（烹饪时间线用）
    selected.sort(key=lambda x: -x["time_minutes"])

    total_time = max(r["time_minutes"] for r in selected) if selected else 0

    # 汇总食材清单
    all_ingredients = {}
    for recipe in selected:
        for ing in recipe["main_ingredients"]:
            cat = categorize_ingredient(ing)
            if cat not in all_ingredients:
                all_ingredients[cat] = []
            if ing not in all_ingredients[cat]:
                all_ingredients[cat].append(ing)

    return {
        "success": True,
        "people": people,
        "style": style or "家常",
        "estimated_time": total_time,
        "dishes": [
            {
                "id": r["id"],
                "name": r["name"],
                "difficulty": r["difficulty"],
                "time_minutes": r["time_minutes"],
                "serves": r["serves"],
                "match_score": r["match_score"],
                "missing_ingredients": r.get("missing_ingredients", []),
                "calories": r.get("calories"),
            }
            for r in selected
        ],
        "ingredient_summary": all_ingredients,
        "cooking_timeline": [
            {
                "order": i + 1,
                "dish": r["name"],
                "time_minutes": r["time_minutes"],
                "tip": "先开始（耗时最长）" if i == 0 else (
                    "可与上一道并行准备" if r["time_minutes"] <= 15 else "等前面的炖上后开始"
                ),
            }
            for i, r in enumerate(selected)
        ],
    }


def main():
    parser = argparse.ArgumentParser(
        description="今日菜单生成器 - 根据食材推荐菜谱"
    )
    parser.add_argument(
        "--ingredients", "-i",
        required=True,
        help="用户手头的食材，逗号分隔，如 '鸡翅,土豆,西红柿,鸡蛋'",
    )
    parser.add_argument(
        "--people", "-p",
        type=int,
        default=2,
        help="就餐人数 (默认 2)",
    )
    parser.add_argument(
        "--style", "-s",
        choices=["家常", "清淡减脂", "快手10分钟", "川湘重口"],
        default=None,
        help="口味风格偏好",
    )
    parser.add_argument(
        "--count", "-c",
        type=int,
        default=None,
        help="期望菜品数量 (默认根据人数自动)",
    )
    parser.add_argument(
        "--time", "-t",
        type=int,
        default=None,
        help="可用烹饪时间（分钟）",
    )
    parser.add_argument(
        "--output", "-o",
        default=None,
        help="输出 JSON 文件路径（默认输出到 stdout）",
    )

    args = parser.parse_args()

    ingredients = [i.strip() for i in args.ingredients.split(",") if i.strip()]

    result = generate_menu(
        user_ingredients=ingredients,
        people=args.people,
        style=args.style,
        count=args.count,
        time_limit=args.time,
    )

    output = json.dumps(result, ensure_ascii=False, indent=2)

    if args.output:
        Path(args.output).write_text(output, encoding="utf-8")
        print(f"菜单已保存到 {args.output}")
    else:
        print(output)


if __name__ == "__main__":
    main()

FILE:daily-menu/references/recipes.md
# 菜谱数据库

内置经典家常菜谱，按风格分类。每道菜标注主料、难度、耗时和详细做法。

---

## 经典家常菜

### 1. 红烧肉 ⭐

- **主料：** 五花肉 500g
- **配料：** 葱、姜
- **调料：** 冰糖/白糖、生抽、老抽、料酒
- **难度：** ⭐⭐ | **耗时：** 50 分钟 | **份量：** 2~3 人

**做法：**
1. 五花肉切 2cm 方块，冷水下锅焯水 3 分钟，捞出洗净浮沫
2. 锅中少许油，放冰糖小火炒至枣红色起大泡（糖色）
3. 下五花肉快速翻炒上色，每块肉均匀裹上糖色
4. 加葱段、姜片、料酒 2 勺、生抽 2 勺、老抽 1 勺翻炒
5. 加开水没过肉，大火烧开后转小火炖 40 分钟
6. 最后大火收汁，汁浓亮即可

**小贴士：** 全程不要加盐，生抽和老抽的咸度足够。加开水而非冷水，肉不会发柴。

---

### 2. 可乐鸡翅

- **主料：** 鸡翅 8~10 个
- **配料：** 可乐 1 罐（330ml）、姜片
- **调料：** 生抽、料酒
- **难度：** ⭐ | **耗时：** 25 分钟 | **份量：** 2 人

**做法：**
1. 鸡翅两面各划 2~3 刀方便入味，冷水下锅焯水捞出
2. 锅中少许油，鸡翅下锅煎至两面金黄（约 3 分钟/面）
3. 倒入可乐没过鸡翅，加生抽 2 勺、姜片 3~4 片
4. 大火烧开转中小火煮 15 分钟
5. 转大火收汁至浓稠，翻动防粘锅

**小贴士：** 用可口可乐比百事更好，甜度更合适。不要用零度可乐，没有糖无法收汁。

---

### 3. 番茄炒蛋

- **主料：** 西红柿 2 个、鸡蛋 3 个
- **配料：** 葱花
- **调料：** 盐、白糖少许
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人

**做法：**
1. 鸡蛋打散加少许盐搅匀，番茄切块（不要太小）
2. 锅中多放点油烧热，倒入蛋液，底部凝固后用铲子推成大块，八分熟盛出
3. 锅中留底油，下番茄块中火翻炒至出汁变软（约 2 分钟）
4. 加半勺糖提鲜（关键），加适量盐
5. 倒回鸡蛋翻炒均匀，出锅撒葱花

**小贴士：** 番茄顶部划十字用开水烫 30 秒可轻松去皮，口感更好。加糖是灵魂。

---

### 4. 酸辣土豆丝

- **主料：** 土豆 2 个
- **配料：** 干辣椒、花椒、蒜末
- **调料：** 醋、盐、鸡精
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人

**做法：**
1. 土豆去皮切细丝（越细越好），泡冷水 5 分钟洗去淀粉，沥干
2. 热锅冷油，小火爆香干辣椒段和花椒（花椒可夹出）
3. 大火下土豆丝，快速翻炒 1~2 分钟，保持脆感
4. 沿锅边淋醋 2 勺（醋遇热锅更香），加盐、鸡精
5. 翻炒均匀，断生即出锅（别炒过头）

**小贴士：** 切好的土豆丝一定要泡水洗掉淀粉，否则会粘连。全程大火快炒才脆。

---

### 5. 蒜蓉西兰花

- **主料：** 西兰花 1 颗
- **配料：** 大蒜 5~6 瓣
- **调料：** 盐、蚝油
- **难度：** ⭐ | **耗时：** 8 分钟 | **份量：** 2 人

**做法：**
1. 西兰花掰成小朵，淡盐水泡 10 分钟洗净
2. 烧开水加几滴油和少许盐，焯水 1 分钟捞出过凉水（保持翠绿）
3. 蒜切末，锅中油烧热爆香蒜末
4. 下西兰花大火翻炒 30 秒
5. 加盐、少许蚝油翻匀出锅

**小贴士：** 焯水时加油加盐能让西兰花更绿更入味。不要炒太久，保持脆感。

---

### 6. 红烧排骨

- **主料：** 排骨 500g
- **配料：** 葱、姜、八角
- **调料：** 冰糖/白糖、生抽、老抽、料酒
- **难度：** ⭐⭐ | **耗时：** 60 分钟 | **份量：** 2~3 人

**做法：**
1. 排骨冷水下锅，加料酒、姜片焯水 5 分钟，捞出洗净
2. 锅中少许油，放冰糖小火炒糖色至枣红色
3. 下排骨翻炒上色，加葱段、姜片、八角 2 颗
4. 加生抽 2 勺、老抽 1 勺、料酒 2 勺翻匀
5. 加开水没过排骨，大火烧开转小火炖 50 分钟
6. 大火收汁，汁浓挂在排骨上即可

**小贴士：** 排骨要充分焯水去血沫。炖的时候不要频繁开盖，保持小火慢炖。

---

### 7. 麻婆豆腐

- **主料：** 豆腐 1 块（北豆腐）、猪肉末 100g
- **配料：** 蒜苗/葱花
- **调料：** 豆瓣酱、花椒粉、生抽、淀粉
- **难度：** ⭐⭐ | **耗时：** 15 分钟 | **份量：** 2 人

**做法：**
1. 豆腐切 1.5cm 方块，烧盐水焯 2 分钟（定型不易碎），捞出
2. 锅中油烧热，下肉末炒散炒香至变色
3. 加 1 大勺豆瓣酱，小火炒出红油（约 1 分钟）
4. 加小半碗水，放入豆腐，轻推不要翻（防碎），中火煮 3 分钟
5. 加生抽调味，水淀粉勾芡，大火收至汤汁浓稠
6. 出锅撒花椒粉和葱花

**小贴士：** 豆腐焯水是关键步骤，不焯水容易碎。全程"推"不要"翻"。

---

### 8. 清炒空心菜

- **主料：** 空心菜 1 把
- **配料：** 大蒜 3~4 瓣、干辣椒 2 个
- **调料：** 盐、白糖少许
- **难度：** ⭐ | **耗时：** 5 分钟 | **份量：** 2 人

**做法：**
1. 空心菜摘洗干净，切段（梗和叶分开）
2. 蒜切末，干辣椒切段
3. 大火热锅热油，爆香蒜末和干辣椒
4. 先下菜梗炒 30 秒，再下菜叶大火快炒
5. 加盐、少许糖（提鲜），断生立即出锅

**小贴士：** 空心菜必须大火快炒，否则发黑。梗和叶分开下锅，熟度才一致。

---

### 9. 清蒸鲈鱼

- **主料：** 鲈鱼 1 条（约 500g）
- **配料：** 葱丝、姜丝、红椒丝
- **调料：** 蒸鱼豉油、料酒
- **难度：** ⭐⭐ | **耗时：** 20 分钟 | **份量：** 2~3 人

**做法：**
1. 鲈鱼去鳞去内脏洗净，鱼身两面各划 3 刀
2. 鱼身抹少许盐和料酒，塞入姜片，腌 10 分钟
3. 盘底铺葱段和姜片（架起鱼身），放上鲈鱼
4. 水烧开后大火蒸 8~10 分钟（鱼眼凸出即熟）
5. 倒掉盘中蒸出的汤汁（腥），铺上葱丝、姜丝、红椒丝
6. 淋上蒸鱼豉油 2 勺，浇上一勺滚烫热油（滋啦一声）

**小贴士：** 蒸鱼关键是火候——水开后再放鱼，大火蒸，时间到立刻取出。蒸过头肉会老。

---

### 10. 冬瓜丸子汤

- **主料：** 冬瓜 300g、猪肉馅 200g
- **配料：** 葱花、姜末、香菜
- **调料：** 盐、胡椒粉、料酒、淀粉
- **难度：** ⭐ | **耗时：** 25 分钟 | **份量：** 2~3 人

**做法：**
1. 冬瓜去皮去瓤切薄片
2. 肉馅加盐、料酒、姜末、少许淀粉，加 2 勺葱姜水，顺一个方向搅打上劲
3. 锅中加水烧至微沸（冒小泡不翻滚）
4. 用勺子挖肉馅，另一手辅助，下入圆丸子（水不要大开，防散）
5. 丸子浮起后下冬瓜片，煮至冬瓜透明（约 5 分钟）
6. 加盐、胡椒粉调味，撒葱花和香菜

**小贴士：** 肉馅一定要搅打上劲（有粘性），丸子才 Q 弹。水保持微沸下丸子，不要大火滚。

---

## 快手 10 分钟菜

### 11. 蒜蓉炒虾仁

- **主料：** 虾仁 200g
- **配料：** 大蒜 5 瓣、葱花
- **调料：** 盐、料酒、胡椒粉
- **难度：** ⭐ | **耗时：** 8 分钟 | **份量：** 2 人

**做法：**
1. 虾仁用料酒和少许盐腌 5 分钟
2. 蒜切末，锅中油爆香蒜末
3. 大火下虾仁翻炒至变色弯曲（约 2 分钟）
4. 加少许盐和胡椒粉，撒葱花出锅

---

### 12. 凉拌黄瓜

- **主料：** 黄瓜 2 根
- **配料：** 大蒜 3 瓣、干辣椒
- **调料：** 醋、生抽、盐、白糖、芝麻油、辣椒油
- **难度：** ⭐ | **耗时：** 5 分钟 | **份量：** 2 人

**做法：**
1. 黄瓜拍碎切段，加少许盐腌 2 分钟挤水
2. 蒜切末，调汁：生抽 2 勺 + 醋 1 勺 + 糖半勺 + 芝麻油 + 辣椒油
3. 浇在黄瓜上拌匀即可

---

### 13. 肥牛金针菇卷

- **主料：** 肥牛卷 200g、金针菇 1 把
- **配料：** 葱花
- **调料：** 生抽、蚝油、蒜蓉
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人

**做法：**
1. 金针菇去根洗净，用肥牛卷裹住金针菇
2. 卷好的肥牛金针菇摆盘
3. 调汁：生抽 2 勺 + 蚝油 1 勺 + 蒜蓉 + 少许水
4. 浇汁，蒸锅上汽蒸 8 分钟
5. 撒葱花，浇热油

---

### 14. 西红柿蛋花汤

- **主料：** 西红柿 1 个、鸡蛋 2 个
- **配料：** 葱花、香菜
- **调料：** 盐、白胡椒粉、芝麻油
- **难度：** ⭐ | **耗时：** 8 分钟 | **份量：** 2 人

**做法：**
1. 番茄切小块，鸡蛋打散
2. 锅中少许油炒软番茄至出汁
3. 加 2 碗水大火烧开
4. 转小火，用筷子引导缓慢倒入蛋液（蛋花更漂亮）
5. 加盐、白胡椒粉，滴几滴香油，撒葱花

---

## 清淡减脂菜

### 15. 白灼虾

- **主料：** 鲜虾 300g
- **配料：** 葱、姜、柠檬
- **调料：** 料酒
- **蘸料：** 生抽 + 姜末 + 蒜末 + 少许醋
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人 | **热量：** ~200kcal

**做法：**
1. 虾去虾线洗净
2. 烧开水，加葱段、姜片、料酒、几片柠檬
3. 水开后下虾，煮至虾变红弯曲（约 2~3 分钟）
4. 捞出过冰水（口感更脆弹）
5. 调蘸料，蘸食即可

---

### 16. 水煮鸡胸肉沙拉

- **主料：** 鸡胸肉 1 块（200g）
- **配料：** 生菜、黄瓜、西红柿、玉米粒
- **调料：** 盐、黑胡椒、橄榄油、柠檬汁
- **难度：** ⭐ | **耗时：** 15 分钟 | **份量：** 1 人 | **热量：** ~300kcal

**做法：**
1. 鸡胸肉冷水下锅加姜片，水开后中火煮 10 分钟，关火焖 5 分钟
2. 捞出放凉撕成丝
3. 蔬菜洗净切块铺底
4. 调汁：橄榄油 + 柠檬汁 + 盐 + 黑胡椒
5. 鸡胸肉丝铺上，淋调汁

---

### 17. 清蒸鳕鱼

- **主料：** 鳕鱼 1 块（200g）
- **配料：** 葱丝、姜丝
- **调料：** 蒸鱼豉油、料酒
- **难度：** ⭐ | **耗时：** 15 分钟 | **份量：** 1 人 | **热量：** ~180kcal

**做法：**
1. 鳕鱼解冻擦干水分，抹料酒和少许盐腌 5 分钟
2. 盘底铺葱姜，放上鳕鱼
3. 水开后大火蒸 8 分钟
4. 倒掉蒸出的水，铺葱姜丝，淋蒸鱼豉油
5. 浇热油激出香味

---

## 川湘重口味菜

### 18. 辣子鸡

- **主料：** 鸡腿肉/鸡翅 400g
- **配料：** 干辣椒一大把、花椒、蒜、姜、葱
- **调料：** 料酒、生抽、盐、白糖、淀粉
- **难度：** ⭐⭐ | **耗时：** 25 分钟 | **份量：** 2~3 人

**做法：**
1. 鸡肉切小块，加盐、料酒、生抽、淀粉腌 15 分钟
2. 油温六成热（筷子入油起小泡），下鸡块炸至金黄捞出
3. 锅留底油，小火煸香干辣椒段和花椒（不要炒糊）
4. 下鸡块大火翻炒，加少许糖、盐
5. 撒葱花和白芝麻出锅

---

### 19. 水煮肉片

- **主料：** 里脊肉/猪肉 300g
- **配料：** 豆芽、生菜/油麦菜、蒜末、葱花
- **调料：** 豆瓣酱、干辣椒、花椒、料酒、生抽、淀粉
- **难度：** ⭐⭐ | **耗时：** 20 分钟 | **份量：** 2~3 人

**做法：**
1. 肉切薄片，加盐、料酒、蛋清、淀粉抓匀腌 10 分钟
2. 蔬菜焯水铺在碗底
3. 锅中油烧热，炒香豆瓣酱出红油，加蒜末、姜末
4. 加水（或高汤）烧开，下肉片拨散，煮至变色（约 1 分钟）
5. 连汤倒在蔬菜上
6. 面上铺蒜末、干辣椒段、花椒，浇一勺滚油（滋啦）

---

### 20. 剁椒鱼头

- **主料：** 鳙鱼头 1 个（胖头鱼）
- **配料：** 剁椒 3 大勺、姜蒜末、葱花
- **调料：** 料酒、生抽、盐
- **难度：** ⭐⭐ | **耗时：** 25 分钟 | **份量：** 2~3 人

**做法：**
1. 鱼头洗净对半剖开，抹盐和料酒腌 10 分钟
2. 盘底铺姜片葱段，放鱼头（切面朝上）
3. 鱼头上铺满剁椒，撒姜蒜末
4. 水开后大火蒸 12~15 分钟
5. 撒葱花，浇热油

---

## 菜品索引（按主料快查）

| 主料 | 可做菜品 |
|------|---------|
| 五花肉 | 红烧肉 |
| 鸡翅 | 可乐鸡翅 |
| 鸡蛋 + 西红柿 | 番茄炒蛋、西红柿蛋花汤 |
| 土豆 | 酸辣土豆丝 |
| 西兰花 | 蒜蓉西兰花 |
| 排骨 | 红烧排骨 |
| 豆腐 + 猪肉 | 麻婆豆腐 |
| 空心菜 | 清炒空心菜 |
| 鲈鱼 | 清蒸鲈鱼 |
| 冬瓜 + 猪肉 | 冬瓜丸子汤 |
| 虾/虾仁 | 蒜蓉炒虾仁、白灼虾 |
| 黄瓜 | 凉拌黄瓜 |
| 肥牛 + 金针菇 | 肥牛金针菇卷 |
| 鸡胸肉 | 水煮鸡胸肉沙拉 |
| 鳕鱼 | 清蒸鳕鱼 |
| 鸡腿/鸡肉 | 辣子鸡 |
| 里脊肉/猪肉 | 水煮肉片 |
| 鳙鱼 | 剁椒鱼头 |

## 菜品风格标签

| 风格 | 菜品编号 |
|------|---------|
| 家常 | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 |
| 快手10分钟 | 3, 4, 5, 8, 11, 12, 13, 14 |
| 清淡减脂 | 5, 14, 15, 16, 17 |
| 川湘重口 | 4, 7, 18, 19, 20 |

FILE:daily-menu/references/ingredients.md
# 食材数据库

所有支持的食材分类和列表。匹配用户输入时支持别名和模糊匹配。

## 肉类（20 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| M01 | 猪肉 | 瘦肉、前腿肉 | 炒、炖、蒸 | 通用肉类 |
| M02 | 五花肉 | 三层肉 | 红烧、煎、烤 | 肥瘦相间，红烧首选 |
| M03 | 排骨 | 肋排、小排 | 红烧、炖、蒸、糖醋 | 需焯水去腥 |
| M04 | 猪蹄 | 猪脚、猪手 | 红烧、炖、卤 | 富含胶原蛋白，炖煮时间长 |
| M05 | 里脊肉 | 猪里脊、小里脊 | 炒、炸、滑溜 | 嫩，适合快炒 |
| M06 | 猪肝 | — | 炒、卤、煮汤 | 需充分清洗，补铁 |
| M07 | 猪大肠 | 肥肠 | 卤、炒、干锅 | 需反复清洗去异味 |
| M08 | 牛肉 | — | 炒、炖、卤 | 纤维粗，需切逆纹 |
| M09 | 牛腩 | — | 炖、红烧、咖喱 | 适合慢炖，越炖越烂 |
| M10 | 牛腱子 | 牛腱 | 卤、炖 | 口感筋道，适合卤制 |
| M11 | 肥牛 | 肥牛卷、肥牛片 | 涮、炒、煮 | 薄片，快熟 |
| M12 | 羊肉 | — | 炖、涮、烤、炒 | 配萝卜去膻味 |
| M13 | 羊排 | — | 烤、炖、红焖 | 带骨更香 |
| M14 | 鸡肉 | 整鸡、鸡块 | 炖、蒸、炒、煮 | 万能蛋白质 |
| M15 | 鸡腿 | 琵琶腿、大鸡腿 | 红烧、烤、卤、炸 | 肉质嫩多汁 |
| M16 | 鸡翅 | 鸡翅中、翅中 | 可乐鸡翅、烤、炸、卤 | 需划刀方便入味 |
| M17 | 鸡爪 | 凤爪 | 卤、炖、泡椒 | 富含胶原蛋白 |
| M18 | 鸡胸肉 | 鸡胸 | 煎、炒、水煮 | 高蛋白低脂，减脂首选 |
| M19 | 鸭肉 | 整鸭、鸭块 | 炖、卤、烤 | 配啤酒或老鸭汤 |
| M20 | 鸭翅 | — | 卤、烤 | 适合卤制入味 |

## 水产海鲜（20 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| S01 | 草鱼 | — | 水煮、红烧、清蒸 | 刺多但肉厚 |
| S02 | 鲫鱼 | — | 煲汤、红烧 | 煲汤奶白色，鲜美 |
| S03 | 鲈鱼 | 海鲈鱼 | 清蒸、红烧 | 刺少肉嫩，清蒸首选 |
| S04 | 黑鱼 | 乌鱼、生鱼 | 酸菜鱼、煲汤 | 肉质紧实 |
| S05 | 黄骨鱼 | 黄辣丁、黄颡鱼 | 煲汤、红烧 | 肉嫩无小刺 |
| S06 | 鲢鱼 | 白鲢 | 水煮、炖 | 经济实惠 |
| S07 | 鳙鱼 | 胖头鱼、花鲢 | 剁椒鱼头、煲汤 | 鱼头大，胶质丰富 |
| S08 | 虾 | 基围虾、大虾、明虾 | 白灼、炒、蒸 | 蛋白质高，快熟 |
| S09 | 小龙虾 | 龙虾 | 蒜蓉、麻辣、十三香 | 需充分刷洗 |
| S10 | 螃蟹 | 大闸蟹、梭子蟹 | 清蒸、炒年糕 | 秋天最肥美 |
| S11 | 花甲 | 蛤蜊、蚬子 | 炒、煮汤、蒸 | 需提前吐沙 |
| S12 | 扇贝 | — | 蒜蓉粉丝蒸 | 蒜蓉蒸最经典 |
| S13 | 生蚝 | 牡蛎、海蛎子 | 蒜蓉烤、煎蛋 | 锌含量高 |
| S14 | 鱿鱼 | — | 炒、烤、干锅 | 需打花刀 |
| S15 | 墨鱼 | 乌贼 | 炒、炖汤 | 可取墨囊 |
| S16 | 八爪鱼 | 章鱼、小章鱼 | 炒、烤、凉拌 | 焯水后口感好 |
| S17 | 带鱼 | — | 煎、红烧、糖醋 | 需去内脏和黑膜 |
| S18 | 黄花鱼 | 黄鱼 | 红烧、煎、炖 | 肉嫩味鲜 |
| S19 | 鳕鱼 | — | 煎、蒸、烤 | 肉质细嫩，无刺 |
| S20 | 三文鱼 | 鲑鱼 | 刺身、煎、烤 | 生食需确保新鲜度 |

## 蛋类 & 豆制品（10 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| E01 | 鸡蛋 | 蛋 | 炒、煎、蒸、煮 | 万能食材 |
| E02 | 鸭蛋 | — | 腌制、煎 | 咸鸭蛋更常见 |
| E03 | 鹅蛋 | — | 煎、蒸 | 个头大，蛋香浓 |
| E04 | 鹌鹑蛋 | — | 卤、煮、炖 | 小巧玲珑 |
| E05 | 豆腐 | 老豆腐、北豆腐 | 红烧、煎、炖 | 质地较硬，适合煎炒 |
| E06 | 嫩豆腐 | 内酯豆腐、南豆腐 | 蒸、煮汤、凉拌 | 质地软嫩 |
| E07 | 冻豆腐 | — | 炖、火锅、煮 | 口感像海绵，吸汁 |
| E08 | 豆干 | 豆腐干、香干 | 炒、卤、凉拌 | 口感紧实 |
| E09 | 千张 | 豆皮、百叶 | 凉拌、炒、卷 | 薄如纸张 |
| E10 | 腐竹 | — | 炖、凉拌、炒 | 需提前泡发 |

## 蔬菜（31 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| V01 | 白菜 | 大白菜 | 炒、炖、煮、腌 | 百搭蔬菜 |
| V02 | 娃娃菜 | 小白菜 | 蒜蓉、煮汤、炒 | 比大白菜更嫩甜 |
| V03 | 菠菜 | — | 炒、煮汤、凉拌 | 焯水去草酸 |
| V04 | 生菜 | — | 生吃、蒜蓉、涮 | 口感脆嫩 |
| V05 | 油麦菜 | — | 蒜蓉、炒 | 类似生菜但更长 |
| V06 | 空心菜 | 通菜、蕹菜 | 清炒、蒜蓉 | 大火快炒防变黑 |
| V07 | 韭菜 | — | 炒蛋、饺子馅 | 香味浓，快熟 |
| V08 | 芹菜 | 西芹 | 炒、凉拌 | 可去筋口感更好 |
| V09 | 香菜 | 芫荽 | 配菜、凉拌 | 提味点缀用 |
| V10 | 茼蒿 | — | 清炒、涮火锅 | 火锅必备蔬菜 |
| V11 | 西兰花 | 绿花菜 | 蒜蓉、白灼、炒 | 焯水后更翠绿 |
| V12 | 菜花 | 花菜、白花菜 | 干锅、炒、烤 | 掰小朵更入味 |
| V13 | 黄瓜 | 青瓜 | 凉拌、炒 | 拍碎比切更入味 |
| V14 | 冬瓜 | — | 炖汤、红烧 | 利尿消肿 |
| V15 | 南瓜 | — | 蒸、煮粥、炒 | 甜糯口感 |
| V16 | 丝瓜 | — | 炒蛋、煮汤 | 去皮后快炒 |
| V17 | 苦瓜 | 凉瓜 | 炒蛋、凉拌 | 焯水可减苦味 |
| V18 | 茄子 | — | 红烧、蒸、烤 | 吸油大户，可先蒸 |
| V19 | 西红柿 | 番茄 | 炒蛋、煮汤、酱 | 万能配菜 |
| V20 | 土豆 | 马铃薯 | 炒丝、炖、焖 | 切丝泡水防变色 |
| V21 | 山药 | 淮山 | 炒、炖、蒸 | 去皮戴手套防痒 |
| V22 | 红薯 | 地瓜、番薯 | 蒸、烤、煮粥 | 软糯香甜 |
| V23 | 胡萝卜 | 红萝卜 | 炒、炖、煮 | 过油更易吸收 |
| V24 | 白萝卜 | — | 炖、煮汤、凉拌 | 冬吃萝卜，清甜 |
| V25 | 洋葱 | — | 炒、配菜、凉拌 | 切丝泡水减辣 |
| V26 | 大蒜 | 蒜头 | 调味、蒜蓉 | 百搭调味 |
| V27 | 生姜 | 姜 | 调味、去腥 | 肉类必备 |
| V28 | 青椒 | 柿子椒 | 炒肉、配菜 | 微辣，口感脆 |
| V29 | 红椒 | 彩椒 | 炒、配色 | 甜脆，提色 |
| V30 | 莲藕 | 藕 | 炒、炖、凉拌 | 脆藕炒，粉藕炖 |
| V31 | 金针菇 | — | 烤、涮、炒 | 需去根部 |

## 干货 & 菌菇（10 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| D01 | 香菇 | 冬菇 | 炒、炖、蒸 | 干香菇需泡发，水可做汤底 |
| D02 | 木耳 | 黑木耳 | 炒、凉拌 | 干木耳泡发后体积增大数倍 |
| D03 | 银耳 | 白木耳 | 甜汤、炖 | 需泡发撕小朵 |
| D04 | 海带 | 昆布 | 炖、凉拌、煮汤 | 需提前泡软 |
| D05 | 紫菜 | — | 煮汤、包饭 | 即食型可直接用 |
| D06 | 腐竹 | — | 炖、凉拌、炒 | 需提前泡发 2~4 小时 |
| D07 | 粉丝 | 龙口粉丝 | 炖、煮、炒 | 热水泡软即可 |
| D08 | 粉条 | 红薯粉条 | 炖、炒 | 口感比粉丝更筋道 |
| D09 | 黄花菜 | 金针菜 | 炒、炖、煮汤 | 干的需泡发，鲜的需焯水 |
| D10 | 茶树菇 | — | 炒、炖 | 干的需泡发，菌香浓 |

## 主食杂粮（10 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| G01 | 大米 | 白米 | 蒸饭、煮粥 | 主食首选 |
| G02 | 小米 | 黄小米 | 煮粥 | 养胃 |
| G03 | 糯米 | 江米 | 粽子、糯米饭、汤圆 | 黏性大 |
| G04 | 玉米 | — | 煮、蒸、炒 | 甜玉米/糯玉米 |
| G05 | 面条 | 挂面、手擀面 | 煮、炒、拌 | 快手主食 |
| G06 | 馒头 | — | 蒸、煎 | 配菜搭档 |
| G07 | 面粉 | 中筋粉 | 包饺子、煎饼、面疙瘩 | 万能主食原料 |
| G08 | 绿豆 | — | 煮汤、煮粥 | 夏天消暑 |
| G09 | 红豆 | 赤小豆 | 煮粥、煮汤 | 需提前泡 |
| G10 | 花生 | — | 炒、煮、炖 | 配菜或零嘴 |

## 默认视为已有的调味料

以下调料在推荐菜谱时默认用户家中已有，不需要额外确认：

- **基础调味：** 盐、白糖、鸡精/味精
- **酱油类：** 生抽、老抽、蚝油
- **酒醋类：** 料酒、米醋/白醋、陈醋
- **油脂类：** 食用油、芝麻油/香油
- **辛香料：** 干辣椒、花椒、八角、桂皮、香叶
- **酱料类：** 豆瓣酱、甜面酱、番茄酱
- **粉类：** 淀粉/生粉、胡椒粉、五香粉、十三香
- **其他：** 葱、蒜、姜（也列在蔬菜中，但作为调味时默认有）

FILE:daily-menu/evals/evals.json
{
  "skill_name": "daily-menu",
  "evals": [
    {
      "id": 1,
      "prompt": "我冰箱里有鸡翅和土豆，今晚做什么菜好？",
      "expected_output": "推荐可乐鸡翅和酸辣土豆丝，给出详细做法和备菜清单",
      "expectations": [
        "推荐的菜品使用了鸡翅和土豆",
        "给出了具体的烹饪步骤和时间",
        "包含备菜清单",
        "菜品荤素搭配"
      ]
    },
    {
      "id": 2,
      "prompt": "家里有五花肉和冬瓜，3个人吃饭，帮我安排一下",
      "expected_output": "推荐红烧肉和冬瓜丸子汤等菜品，考虑3人份量",
      "expectations": [
        "推荐的菜用到了五花肉和冬瓜",
        "考虑了3人的份量",
        "给出了烹饪时间线建议"
      ]
    },
    {
      "id": 3,
      "prompt": "我在减肥，有鸡胸肉和西兰花，推荐减脂餐",
      "expected_output": "推荐清淡减脂菜品如水煮鸡胸肉沙拉和蒜蓉西兰花",
      "expectations": [
        "推荐的菜符合减脂风格",
        "给出了热量估算",
        "烹饪方式清淡（蒸、煮、白灼等）"
      ]
    },
    {
      "id": 4,
      "prompt": "只有10分钟，虾和黄瓜能做啥？",
      "expected_output": "推荐蒜蓉炒虾仁和凉拌黄瓜等快手菜",
      "expectations": [
        "推荐的菜品都在10分钟以内",
        "用到了虾和黄瓜",
        "做法简单快捷"
      ]
    },
    {
      "id": 5,
      "prompt": "今天想吃辣的，家里有里脊肉和豆腐",
      "expected_output": "推荐川湘重口味菜品如水煮肉片和麻婆豆腐",
      "expectations": [
        "推荐的菜品是重口味/川湘风格",
        "用到了里脊肉和豆腐",
        "包含辣椒/花椒等调料"
      ]
    }
  ]
}

---
name: daily-menu
description: >-
  生成今日菜单推荐。根据用户手头的食材、口味偏好、人数和烹饪时间，
  从内置食材库和菜谱库中智能匹配，输出完整的菜单方案和分步烹饪指南。
  当用户提到"今天吃什么""做什么菜""菜单""菜谱推荐""晚饭吃啥"等意图时触发。
---

# 今日菜单生成器

根据用户现有食材、口味偏好、就餐人数和可用时间，生成个性化菜单推荐和烹饪指南。

## 工作流程

### 第一步：了解用户需求

通过简短对话收集以下信息（缺失项用合理默认值）：

| 信息项 | 默认值 | 说明 |
|--------|--------|------|
| 手头食材 | — | **必问**，至少确认 1~3 种主要食材 |
| 就餐人数 | 2 人 | 影响份量建议 |
| 口味偏好 | 家常 | 家常 / 清淡减脂 / 川湘重口 / 快手10分钟 |
| 可用时间 | 60 分钟 | 影响菜品复杂度 |
| 忌口/过敏 | 无 | 如有则排除相关食材 |
| 菜品数量 | 2~4 道 | 根据人数自动建议 |

**对话原则：**
- 不要一次问太多问题，最核心的是「你手头有什么食材？」
- 如果用户只说了食材，其他用默认值直接推荐
- 语气轻松友好，像朋友聊天一样

### 第二步：匹配菜谱

1. 读取 `references/ingredients.md` 获取完整食材分类
2. 读取 `references/recipes.md` 获取菜谱库
3. 根据用户提供的食材，从菜谱库中匹配可做的菜品
4. 考虑荤素搭配、营养均衡、烹饪难度

**匹配规则：**
- 主料必须匹配（用户手头有的食材）
- 常见调料（盐、酱油、醋、糖、料酒、蚝油等）默认家里有，不需要确认
- 优先推荐主料完全匹配的菜，其次推荐只差 1~2 种配料的菜
- 如果用户食材能做的菜不够，可以建议额外采购少量食材

### 第三步：输出菜单

使用以下格式输出：

```
## 🍽️ 今日菜单推荐

**就餐人数：** X 人 | **预计用时：** X 分钟 | **风格：** XXX

---

### 1. 菜名 ⭐
> 一句话点评这道菜的特点

**食材：**
- 主料：XXX
- 配料：XXX
- 调料：XXX

**做法：**
1. 第一步（附时间和火候）
2. 第二步
3. ...

**小贴士：** 实用烹饪技巧

---

### 2. 菜名
（同上格式）

---

## 📋 备菜清单

把所有菜需要的食材汇总，方便一次性准备：

| 分类 | 食材 | 用量 | 处理方式 |
|------|------|------|----------|
| 肉类 | ... | ... | ... |
| 蔬菜 | ... | ... | ... |

## ⏱️ 烹饪时间线

建议的做菜顺序和并行操作：
1. 先做 XX（耗时最长的先开始）
2. 在等待的同时准备 XX
3. 最后快炒 XX
```

### 第四步：后续互动

菜单输出后，主动询问：
- 「要不要换掉某道菜？」
- 「要不要看更详细的某道菜做法？」
- 「还想加个汤/凉菜吗？」

## 口味风格指南

### 家常风格（默认）
- 红烧、清炒、炖煮为主
- 调味适中，老少皆宜
- 代表菜：红烧肉、番茄炒蛋、清炒时蔬

### 清淡减脂
- 少油少盐，以蒸、煮、白灼为主
- 多蔬菜，蛋白质优先选鸡胸肉/鱼/虾/豆腐
- 减少碳水，避免油炸
- 标注估算热量

### 快手 10 分钟
- 只推荐炒、拌、煮等快速烹饪方式
- 食材处理简单（切丝切片为主）
- 每道菜控制在 10 分钟以内

### 川湘重口味
- 麻辣鲜香，重油重味
- 豆瓣酱、辣椒、花椒、剁椒等调料
- 代表菜：麻婆豆腐、辣子鸡、酸辣土豆丝

## 重要原则

1. **实用优先**：做法描述要具体到火候、时间、用量，不要含糊
2. **荤素搭配**：2 道菜以上时确保有荤有素
3. **难度递进**：多道菜时从简到难排列
4. **时间合理**：给出的总用时要考虑并行操作
5. **食材不浪费**：尽量用完用户提到的食材
6. **安全第一**：涉及生食（如三文鱼）要提醒新鲜度要求

FILE:scripts/generate_menu.py
#!/usr/bin/env python3
"""
今日菜单生成器 - 根据用户食材自动匹配菜谱并生成菜单方案。

用法:
    python scripts/generate_menu.py --ingredients "鸡翅,土豆,西红柿,鸡蛋"
    python scripts/generate_menu.py --ingredients "五花肉,冬瓜" --people 4 --style 家常
    python scripts/generate_menu.py --ingredients "鸡胸肉,黄瓜,西兰花" --style 清淡减脂
    python scripts/generate_menu.py --ingredients "里脊肉,豆腐" --style 川湘重口 --count 3
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path
from typing import Optional


# ── 菜谱数据 ──────────────────────────────────────────────────────────

RECIPES = [
    {
        "id": 1,
        "name": "红烧肉",
        "main_ingredients": ["五花肉"],
        "styles": ["家常"],
        "difficulty": 2,
        "time_minutes": 50,
        "serves": "2~3人",
    },
    {
        "id": 2,
        "name": "可乐鸡翅",
        "main_ingredients": ["鸡翅"],
        "styles": ["家常"],
        "difficulty": 1,
        "time_minutes": 25,
        "serves": "2人",
    },
    {
        "id": 3,
        "name": "番茄炒蛋",
        "main_ingredients": ["西红柿", "鸡蛋"],
        "styles": ["家常", "快手10分钟"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
    },
    {
        "id": 4,
        "name": "酸辣土豆丝",
        "main_ingredients": ["土豆"],
        "styles": ["家常", "快手10分钟", "川湘重口"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
    },
    {
        "id": 5,
        "name": "蒜蓉西兰花",
        "main_ingredients": ["西兰花"],
        "styles": ["家常", "快手10分钟", "清淡减脂"],
        "difficulty": 1,
        "time_minutes": 8,
        "serves": "2人",
    },
    {
        "id": 6,
        "name": "红烧排骨",
        "main_ingredients": ["排骨"],
        "styles": ["家常"],
        "difficulty": 2,
        "time_minutes": 60,
        "serves": "2~3人",
    },
    {
        "id": 7,
        "name": "麻婆豆腐",
        "main_ingredients": ["豆腐", "猪肉"],
        "styles": ["家常", "川湘重口"],
        "difficulty": 2,
        "time_minutes": 15,
        "serves": "2人",
    },
    {
        "id": 8,
        "name": "清炒空心菜",
        "main_ingredients": ["空心菜"],
        "styles": ["家常", "快手10分钟"],
        "difficulty": 1,
        "time_minutes": 5,
        "serves": "2人",
    },
    {
        "id": 9,
        "name": "清蒸鲈鱼",
        "main_ingredients": ["鲈鱼"],
        "styles": ["家常"],
        "difficulty": 2,
        "time_minutes": 20,
        "serves": "2~3人",
    },
    {
        "id": 10,
        "name": "冬瓜丸子汤",
        "main_ingredients": ["冬瓜", "猪肉"],
        "styles": ["家常"],
        "difficulty": 1,
        "time_minutes": 25,
        "serves": "2~3人",
    },
    {
        "id": 11,
        "name": "蒜蓉炒虾仁",
        "main_ingredients": ["虾"],
        "styles": ["快手10分钟"],
        "difficulty": 1,
        "time_minutes": 8,
        "serves": "2人",
    },
    {
        "id": 12,
        "name": "凉拌黄瓜",
        "main_ingredients": ["黄瓜"],
        "styles": ["快手10分钟"],
        "difficulty": 1,
        "time_minutes": 5,
        "serves": "2人",
    },
    {
        "id": 13,
        "name": "肥牛金针菇卷",
        "main_ingredients": ["肥牛", "金针菇"],
        "styles": ["快手10分钟"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
    },
    {
        "id": 14,
        "name": "西红柿蛋花汤",
        "main_ingredients": ["西红柿", "鸡蛋"],
        "styles": ["快手10分钟", "清淡减脂"],
        "difficulty": 1,
        "time_minutes": 8,
        "serves": "2人",
    },
    {
        "id": 15,
        "name": "白灼虾",
        "main_ingredients": ["虾"],
        "styles": ["清淡减脂"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
        "calories": "~200kcal",
    },
    {
        "id": 16,
        "name": "水煮鸡胸肉沙拉",
        "main_ingredients": ["鸡胸肉"],
        "styles": ["清淡减脂"],
        "difficulty": 1,
        "time_minutes": 15,
        "serves": "1人",
        "calories": "~300kcal",
    },
    {
        "id": 17,
        "name": "清蒸鳕鱼",
        "main_ingredients": ["鳕鱼"],
        "styles": ["清淡减脂"],
        "difficulty": 1,
        "time_minutes": 15,
        "serves": "1人",
        "calories": "~180kcal",
    },
    {
        "id": 18,
        "name": "辣子鸡",
        "main_ingredients": ["鸡腿", "鸡翅", "鸡肉"],
        "styles": ["川湘重口"],
        "difficulty": 2,
        "time_minutes": 25,
        "serves": "2~3人",
    },
    {
        "id": 19,
        "name": "水煮肉片",
        "main_ingredients": ["里脊肉", "猪肉"],
        "styles": ["川湘重口"],
        "difficulty": 2,
        "time_minutes": 20,
        "serves": "2~3人",
    },
    {
        "id": 20,
        "name": "剁椒鱼头",
        "main_ingredients": ["鳙鱼"],
        "styles": ["川湘重口"],
        "difficulty": 2,
        "time_minutes": 25,
        "serves": "2~3人",
    },
]

# 食材别名映射 → 标准名
ALIASES = {
    "番茄": "西红柿",
    "蕃茄": "西红柿",
    "洋柿子": "西红柿",
    "瘦肉": "猪肉",
    "前腿肉": "猪肉",
    "肉末": "猪肉",
    "肉馅": "猪肉",
    "猪里脊": "里脊肉",
    "小里脊": "里脊肉",
    "肥肠": "猪大肠",
    "猪手": "猪蹄",
    "猪脚": "猪蹄",
    "牛腱": "牛腱子",
    "肥牛卷": "肥牛",
    "肥牛片": "肥牛",
    "琵琶腿": "鸡腿",
    "大鸡腿": "鸡腿",
    "鸡翅中": "鸡翅",
    "翅中": "鸡翅",
    "凤爪": "鸡爪",
    "鸡胸": "鸡胸肉",
    "海鲈鱼": "鲈鱼",
    "基围虾": "虾",
    "大虾": "虾",
    "明虾": "虾",
    "虾仁": "虾",
    "龙虾": "小龙虾",
    "蛤蜊": "花甲",
    "蚬子": "花甲",
    "牡蛎": "生蚝",
    "海蛎子": "生蚝",
    "乌贼": "墨鱼",
    "章鱼": "八爪鱼",
    "小章鱼": "八爪鱼",
    "黄鱼": "黄花鱼",
    "鲑鱼": "三文鱼",
    "胖头鱼": "鳙鱼",
    "花鲢": "鳙鱼",
    "蛋": "鸡蛋",
    "老豆腐": "豆腐",
    "北豆腐": "豆腐",
    "内酯豆腐": "嫩豆腐",
    "南豆腐": "嫩豆腐",
    "豆腐干": "豆干",
    "香干": "豆干",
    "豆皮": "千张",
    "百叶": "千张",
    "大白菜": "白菜",
    "小白菜": "娃娃菜",
    "通菜": "空心菜",
    "蕹菜": "空心菜",
    "西芹": "芹菜",
    "芫荽": "香菜",
    "绿花菜": "西兰花",
    "花菜": "菜花",
    "白花菜": "菜花",
    "青瓜": "黄瓜",
    "凉瓜": "苦瓜",
    "马铃薯": "土豆",
    "淮山": "山药",
    "地瓜": "红薯",
    "番薯": "红薯",
    "红萝卜": "胡萝卜",
    "蒜头": "大蒜",
    "蒜": "大蒜",
    "姜": "生姜",
    "柿子椒": "青椒",
    "彩椒": "红椒",
    "藕": "莲藕",
    "冬菇": "香菇",
    "黑木耳": "木耳",
    "白木耳": "银耳",
    "昆布": "海带",
    "龙口粉丝": "粉丝",
    "红薯粉条": "粉条",
    "金针菜": "黄花菜",
    "白米": "大米",
    "黄小米": "小米",
    "江米": "糯米",
    "挂面": "面条",
    "手擀面": "面条",
    "中筋粉": "面粉",
    "赤小豆": "红豆",
}


def normalize_ingredient(name: str) -> str:
    """将用户输入的食材名标准化。"""
    name = name.strip()
    return ALIASES.get(name, name)


def match_recipes(user_ingredients: list[str], style: str | None = None) -> list[dict]:
    """根据用户食材和风格偏好匹配菜谱。

    返回按匹配度排序的菜谱列表，每个菜谱附带 match_score。
    """
    normalized = [normalize_ingredient(i) for i in user_ingredients]
    results = []

    for recipe in RECIPES:
        # 风格过滤
        if style and style not in recipe["styles"]:
            continue

        # 计算主料匹配度
        required = recipe["main_ingredients"]
        matched = sum(1 for r in required if r in normalized)

        if matched == 0:
            continue

        score = matched / len(required)  # 1.0 = 完全匹配
        missing = [r for r in required if r not in normalized]

        results.append({
            **recipe,
            "match_score": score,
            "missing_ingredients": missing,
        })

    # 按匹配度降序、难度升序排列
    results.sort(key=lambda x: (-x["match_score"], x["difficulty"]))
    return results


def categorize_ingredient(name: str) -> str:
    """判断食材类别。"""
    meat = {"猪肉", "五花肉", "排骨", "猪蹄", "里脊肉", "猪肝", "猪大肠",
            "牛肉", "牛腩", "牛腱子", "肥牛", "羊肉", "羊排",
            "鸡肉", "鸡腿", "鸡翅", "鸡爪", "鸡胸肉", "鸭肉", "鸭翅"}
    seafood = {"草鱼", "鲫鱼", "鲈鱼", "黑鱼", "黄骨鱼", "鲢鱼", "鳙鱼",
               "虾", "小龙虾", "螃蟹", "花甲", "扇贝", "生蚝",
               "鱿鱼", "墨鱼", "八爪鱼", "带鱼", "黄花鱼", "鳕鱼", "三文鱼"}
    egg_tofu = {"鸡蛋", "鸭蛋", "鹅蛋", "鹌鹑蛋",
                "豆腐", "嫩豆腐", "冻豆腐", "豆干", "千张", "腐竹"}
    vegs = {"白菜", "娃娃菜", "菠菜", "生菜", "油麦菜", "空心菜", "韭菜",
            "芹菜", "香菜", "茼蒿", "西兰花", "菜花", "黄瓜", "冬瓜",
            "南瓜", "丝瓜", "苦瓜", "茄子", "西红柿", "土豆", "山药",
            "红薯", "胡萝卜", "白萝卜", "洋葱", "大蒜", "生姜",
            "青椒", "红椒", "莲藕", "金针菇"}
    dried = {"香菇", "木耳", "银耳", "海带", "紫菜", "粉丝", "粉条", "黄花菜", "茶树菇"}
    staple = {"大米", "小米", "糯米", "玉米", "面条", "馒头", "面粉", "绿豆", "红豆", "花生"}

    n = normalize_ingredient(name)
    if n in meat:
        return "肉类"
    if n in seafood:
        return "水产海鲜"
    if n in egg_tofu:
        return "蛋类/豆制品"
    if n in vegs:
        return "蔬菜"
    if n in dried:
        return "干货/菌菇"
    if n in staple:
        return "主食杂粮"
    return "其他"


def generate_menu(
    user_ingredients: list[str],
    people: int = 2,
    style: str | None = None,
    count: int | None = None,
    time_limit: int | None = None,
) -> dict:
    """生成完整菜单方案。

    Args:
        user_ingredients: 用户手头的食材列表
        people: 就餐人数
        style: 口味偏好（家常/清淡减脂/快手10分钟/川湘重口）
        count: 期望菜品数量
        time_limit: 可用烹饪时间（分钟）

    Returns:
        包含推荐菜品、备菜清单、时间线的字典
    """
    if count is None:
        count = min(max(2, people), 4)  # 2~4 道菜

    # 匹配菜谱
    matched = match_recipes(user_ingredients, style)

    if not matched:
        return {
            "success": False,
            "message": "抱歉，根据你提供的食材暂时没有匹配的菜谱。",
            "user_ingredients": user_ingredients,
            "suggestions": "试试提供更多食材，或者换个口味风格？",
        }

    # 选菜策略：荤素搭配
    selected = []
    has_meat = False
    has_veg = False

    for recipe in matched:
        if len(selected) >= count:
            break

        # 时间限制
        if time_limit and recipe["time_minutes"] > time_limit:
            continue

        # 判断荤素
        is_meat = any(
            categorize_ingredient(i) in ("肉类", "水产海鲜")
            for i in recipe["main_ingredients"]
        )

        selected.append({**recipe, "is_meat": is_meat})
        if is_meat:
            has_meat = True
        else:
            has_veg = True

    # 如果只有荤或只有素，且还有余量，补充
    if len(selected) < count and selected:
        for recipe in matched:
            if recipe["id"] in [s["id"] for s in selected]:
                continue
            if len(selected) >= count:
                break

            is_meat = any(
                categorize_ingredient(i) in ("肉类", "水产海鲜")
                for i in recipe["main_ingredients"]
            )

            if (not has_veg and not is_meat) or (not has_meat and is_meat):
                selected.append({**recipe, "is_meat": is_meat})
                if is_meat:
                    has_meat = True
                else:
                    has_veg = True

    # 按耗时从长到短排列（烹饪时间线用）
    selected.sort(key=lambda x: -x["time_minutes"])

    total_time = max(r["time_minutes"] for r in selected) if selected else 0

    # 汇总食材清单
    all_ingredients = {}
    for recipe in selected:
        for ing in recipe["main_ingredients"]:
            cat = categorize_ingredient(ing)
            if cat not in all_ingredients:
                all_ingredients[cat] = []
            if ing not in all_ingredients[cat]:
                all_ingredients[cat].append(ing)

    return {
        "success": True,
        "people": people,
        "style": style or "家常",
        "estimated_time": total_time,
        "dishes": [
            {
                "id": r["id"],
                "name": r["name"],
                "difficulty": r["difficulty"],
                "time_minutes": r["time_minutes"],
                "serves": r["serves"],
                "match_score": r["match_score"],
                "missing_ingredients": r.get("missing_ingredients", []),
                "calories": r.get("calories"),
            }
            for r in selected
        ],
        "ingredient_summary": all_ingredients,
        "cooking_timeline": [
            {
                "order": i + 1,
                "dish": r["name"],
                "time_minutes": r["time_minutes"],
                "tip": "先开始（耗时最长）" if i == 0 else (
                    "可与上一道并行准备" if r["time_minutes"] <= 15 else "等前面的炖上后开始"
                ),
            }
            for i, r in enumerate(selected)
        ],
    }


def main():
    parser = argparse.ArgumentParser(
        description="今日菜单生成器 - 根据食材推荐菜谱"
    )
    parser.add_argument(
        "--ingredients", "-i",
        required=True,
        help="用户手头的食材，逗号分隔，如 '鸡翅,土豆,西红柿,鸡蛋'",
    )
    parser.add_argument(
        "--people", "-p",
        type=int,
        default=2,
        help="就餐人数 (默认 2)",
    )
    parser.add_argument(
        "--style", "-s",
        choices=["家常", "清淡减脂", "快手10分钟", "川湘重口"],
        default=None,
        help="口味风格偏好",
    )
    parser.add_argument(
        "--count", "-c",
        type=int,
        default=None,
        help="期望菜品数量 (默认根据人数自动)",
    )
    parser.add_argument(
        "--time", "-t",
        type=int,
        default=None,
        help="可用烹饪时间（分钟）",
    )
    parser.add_argument(
        "--output", "-o",
        default=None,
        help="输出 JSON 文件路径（默认输出到 stdout）",
    )

    args = parser.parse_args()

    ingredients = [i.strip() for i in args.ingredients.split(",") if i.strip()]

    result = generate_menu(
        user_ingredients=ingredients,
        people=args.people,
        style=args.style,
        count=args.count,
        time_limit=args.time,
    )

    output = json.dumps(result, ensure_ascii=False, indent=2)

    if args.output:
        Path(args.output).write_text(output, encoding="utf-8")
        print(f"菜单已保存到 {args.output}")
    else:
        print(output)


if __name__ == "__main__":
    main()

FILE:references/recipes.md
# 菜谱数据库

内置经典家常菜谱，按风格分类。每道菜标注主料、难度、耗时和详细做法。

---

## 经典家常菜

### 1. 红烧肉 ⭐

- **主料：** 五花肉 500g
- **配料：** 葱、姜
- **调料：** 冰糖/白糖、生抽、老抽、料酒
- **难度：** ⭐⭐ | **耗时：** 50 分钟 | **份量：** 2~3 人

**做法：**
1. 五花肉切 2cm 方块，冷水下锅焯水 3 分钟，捞出洗净浮沫
2. 锅中少许油，放冰糖小火炒至枣红色起大泡（糖色）
3. 下五花肉快速翻炒上色，每块肉均匀裹上糖色
4. 加葱段、姜片、料酒 2 勺、生抽 2 勺、老抽 1 勺翻炒
5. 加开水没过肉，大火烧开后转小火炖 40 分钟
6. 最后大火收汁，汁浓亮即可

**小贴士：** 全程不要加盐，生抽和老抽的咸度足够。加开水而非冷水，肉不会发柴。

---

### 2. 可乐鸡翅

- **主料：** 鸡翅 8~10 个
- **配料：** 可乐 1 罐（330ml）、姜片
- **调料：** 生抽、料酒
- **难度：** ⭐ | **耗时：** 25 分钟 | **份量：** 2 人

**做法：**
1. 鸡翅两面各划 2~3 刀方便入味，冷水下锅焯水捞出
2. 锅中少许油，鸡翅下锅煎至两面金黄（约 3 分钟/面）
3. 倒入可乐没过鸡翅，加生抽 2 勺、姜片 3~4 片
4. 大火烧开转中小火煮 15 分钟
5. 转大火收汁至浓稠，翻动防粘锅

**小贴士：** 用可口可乐比百事更好，甜度更合适。不要用零度可乐，没有糖无法收汁。

---

### 3. 番茄炒蛋

- **主料：** 西红柿 2 个、鸡蛋 3 个
- **配料：** 葱花
- **调料：** 盐、白糖少许
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人

**做法：**
1. 鸡蛋打散加少许盐搅匀，番茄切块（不要太小）
2. 锅中多放点油烧热，倒入蛋液，底部凝固后用铲子推成大块，八分熟盛出
3. 锅中留底油，下番茄块中火翻炒至出汁变软（约 2 分钟）
4. 加半勺糖提鲜（关键），加适量盐
5. 倒回鸡蛋翻炒均匀，出锅撒葱花

**小贴士：** 番茄顶部划十字用开水烫 30 秒可轻松去皮，口感更好。加糖是灵魂。

---

### 4. 酸辣土豆丝

- **主料：** 土豆 2 个
- **配料：** 干辣椒、花椒、蒜末
- **调料：** 醋、盐、鸡精
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人

**做法：**
1. 土豆去皮切细丝（越细越好），泡冷水 5 分钟洗去淀粉，沥干
2. 热锅冷油，小火爆香干辣椒段和花椒（花椒可夹出）
3. 大火下土豆丝，快速翻炒 1~2 分钟，保持脆感
4. 沿锅边淋醋 2 勺（醋遇热锅更香），加盐、鸡精
5. 翻炒均匀，断生即出锅（别炒过头）

**小贴士：** 切好的土豆丝一定要泡水洗掉淀粉，否则会粘连。全程大火快炒才脆。

---

### 5. 蒜蓉西兰花

- **主料：** 西兰花 1 颗
- **配料：** 大蒜 5~6 瓣
- **调料：** 盐、蚝油
- **难度：** ⭐ | **耗时：** 8 分钟 | **份量：** 2 人

**做法：**
1. 西兰花掰成小朵，淡盐水泡 10 分钟洗净
2. 烧开水加几滴油和少许盐，焯水 1 分钟捞出过凉水（保持翠绿）
3. 蒜切末，锅中油烧热爆香蒜末
4. 下西兰花大火翻炒 30 秒
5. 加盐、少许蚝油翻匀出锅

**小贴士：** 焯水时加油加盐能让西兰花更绿更入味。不要炒太久，保持脆感。

---

### 6. 红烧排骨

- **主料：** 排骨 500g
- **配料：** 葱、姜、八角
- **调料：** 冰糖/白糖、生抽、老抽、料酒
- **难度：** ⭐⭐ | **耗时：** 60 分钟 | **份量：** 2~3 人

**做法：**
1. 排骨冷水下锅，加料酒、姜片焯水 5 分钟，捞出洗净
2. 锅中少许油，放冰糖小火炒糖色至枣红色
3. 下排骨翻炒上色，加葱段、姜片、八角 2 颗
4. 加生抽 2 勺、老抽 1 勺、料酒 2 勺翻匀
5. 加开水没过排骨，大火烧开转小火炖 50 分钟
6. 大火收汁，汁浓挂在排骨上即可

**小贴士：** 排骨要充分焯水去血沫。炖的时候不要频繁开盖，保持小火慢炖。

---

### 7. 麻婆豆腐

- **主料：** 豆腐 1 块（北豆腐）、猪肉末 100g
- **配料：** 蒜苗/葱花
- **调料：** 豆瓣酱、花椒粉、生抽、淀粉
- **难度：** ⭐⭐ | **耗时：** 15 分钟 | **份量：** 2 人

**做法：**
1. 豆腐切 1.5cm 方块，烧盐水焯 2 分钟（定型不易碎），捞出
2. 锅中油烧热，下肉末炒散炒香至变色
3. 加 1 大勺豆瓣酱，小火炒出红油（约 1 分钟）
4. 加小半碗水，放入豆腐，轻推不要翻（防碎），中火煮 3 分钟
5. 加生抽调味，水淀粉勾芡，大火收至汤汁浓稠
6. 出锅撒花椒粉和葱花

**小贴士：** 豆腐焯水是关键步骤，不焯水容易碎。全程"推"不要"翻"。

---

### 8. 清炒空心菜

- **主料：** 空心菜 1 把
- **配料：** 大蒜 3~4 瓣、干辣椒 2 个
- **调料：** 盐、白糖少许
- **难度：** ⭐ | **耗时：** 5 分钟 | **份量：** 2 人

**做法：**
1. 空心菜摘洗干净，切段（梗和叶分开）
2. 蒜切末，干辣椒切段
3. 大火热锅热油，爆香蒜末和干辣椒
4. 先下菜梗炒 30 秒，再下菜叶大火快炒
5. 加盐、少许糖（提鲜），断生立即出锅

**小贴士：** 空心菜必须大火快炒，否则发黑。梗和叶分开下锅，熟度才一致。

---

### 9. 清蒸鲈鱼

- **主料：** 鲈鱼 1 条（约 500g）
- **配料：** 葱丝、姜丝、红椒丝
- **调料：** 蒸鱼豉油、料酒
- **难度：** ⭐⭐ | **耗时：** 20 分钟 | **份量：** 2~3 人

**做法：**
1. 鲈鱼去鳞去内脏洗净，鱼身两面各划 3 刀
2. 鱼身抹少许盐和料酒，塞入姜片，腌 10 分钟
3. 盘底铺葱段和姜片（架起鱼身），放上鲈鱼
4. 水烧开后大火蒸 8~10 分钟（鱼眼凸出即熟）
5. 倒掉盘中蒸出的汤汁（腥），铺上葱丝、姜丝、红椒丝
6. 淋上蒸鱼豉油 2 勺，浇上一勺滚烫热油（滋啦一声）

**小贴士：** 蒸鱼关键是火候——水开后再放鱼，大火蒸，时间到立刻取出。蒸过头肉会老。

---

### 10. 冬瓜丸子汤

- **主料：** 冬瓜 300g、猪肉馅 200g
- **配料：** 葱花、姜末、香菜
- **调料：** 盐、胡椒粉、料酒、淀粉
- **难度：** ⭐ | **耗时：** 25 分钟 | **份量：** 2~3 人

**做法：**
1. 冬瓜去皮去瓤切薄片
2. 肉馅加盐、料酒、姜末、少许淀粉，加 2 勺葱姜水，顺一个方向搅打上劲
3. 锅中加水烧至微沸（冒小泡不翻滚）
4. 用勺子挖肉馅，另一手辅助，下入圆丸子（水不要大开，防散）
5. 丸子浮起后下冬瓜片，煮至冬瓜透明（约 5 分钟）
6. 加盐、胡椒粉调味，撒葱花和香菜

**小贴士：** 肉馅一定要搅打上劲（有粘性），丸子才 Q 弹。水保持微沸下丸子，不要大火滚。

---

## 快手 10 分钟菜

### 11. 蒜蓉炒虾仁

- **主料：** 虾仁 200g
- **配料：** 大蒜 5 瓣、葱花
- **调料：** 盐、料酒、胡椒粉
- **难度：** ⭐ | **耗时：** 8 分钟 | **份量：** 2 人

**做法：**
1. 虾仁用料酒和少许盐腌 5 分钟
2. 蒜切末，锅中油爆香蒜末
3. 大火下虾仁翻炒至变色弯曲（约 2 分钟）
4. 加少许盐和胡椒粉，撒葱花出锅

---

### 12. 凉拌黄瓜

- **主料：** 黄瓜 2 根
- **配料：** 大蒜 3 瓣、干辣椒
- **调料：** 醋、生抽、盐、白糖、芝麻油、辣椒油
- **难度：** ⭐ | **耗时：** 5 分钟 | **份量：** 2 人

**做法：**
1. 黄瓜拍碎切段，加少许盐腌 2 分钟挤水
2. 蒜切末，调汁：生抽 2 勺 + 醋 1 勺 + 糖半勺 + 芝麻油 + 辣椒油
3. 浇在黄瓜上拌匀即可

---

### 13. 肥牛金针菇卷

- **主料：** 肥牛卷 200g、金针菇 1 把
- **配料：** 葱花
- **调料：** 生抽、蚝油、蒜蓉
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人

**做法：**
1. 金针菇去根洗净，用肥牛卷裹住金针菇
2. 卷好的肥牛金针菇摆盘
3. 调汁：生抽 2 勺 + 蚝油 1 勺 + 蒜蓉 + 少许水
4. 浇汁，蒸锅上汽蒸 8 分钟
5. 撒葱花，浇热油

---

### 14. 西红柿蛋花汤

- **主料：** 西红柿 1 个、鸡蛋 2 个
- **配料：** 葱花、香菜
- **调料：** 盐、白胡椒粉、芝麻油
- **难度：** ⭐ | **耗时：** 8 分钟 | **份量：** 2 人

**做法：**
1. 番茄切小块，鸡蛋打散
2. 锅中少许油炒软番茄至出汁
3. 加 2 碗水大火烧开
4. 转小火，用筷子引导缓慢倒入蛋液（蛋花更漂亮）
5. 加盐、白胡椒粉，滴几滴香油，撒葱花

---

## 清淡减脂菜

### 15. 白灼虾

- **主料：** 鲜虾 300g
- **配料：** 葱、姜、柠檬
- **调料：** 料酒
- **蘸料：** 生抽 + 姜末 + 蒜末 + 少许醋
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人 | **热量：** ~200kcal

**做法：**
1. 虾去虾线洗净
2. 烧开水，加葱段、姜片、料酒、几片柠檬
3. 水开后下虾，煮至虾变红弯曲（约 2~3 分钟）
4. 捞出过冰水（口感更脆弹）
5. 调蘸料，蘸食即可

---

### 16. 水煮鸡胸肉沙拉

- **主料：** 鸡胸肉 1 块（200g）
- **配料：** 生菜、黄瓜、西红柿、玉米粒
- **调料：** 盐、黑胡椒、橄榄油、柠檬汁
- **难度：** ⭐ | **耗时：** 15 分钟 | **份量：** 1 人 | **热量：** ~300kcal

**做法：**
1. 鸡胸肉冷水下锅加姜片，水开后中火煮 10 分钟，关火焖 5 分钟
2. 捞出放凉撕成丝
3. 蔬菜洗净切块铺底
4. 调汁：橄榄油 + 柠檬汁 + 盐 + 黑胡椒
5. 鸡胸肉丝铺上，淋调汁

---

### 17. 清蒸鳕鱼

- **主料：** 鳕鱼 1 块（200g）
- **配料：** 葱丝、姜丝
- **调料：** 蒸鱼豉油、料酒
- **难度：** ⭐ | **耗时：** 15 分钟 | **份量：** 1 人 | **热量：** ~180kcal

**做法：**
1. 鳕鱼解冻擦干水分，抹料酒和少许盐腌 5 分钟
2. 盘底铺葱姜，放上鳕鱼
3. 水开后大火蒸 8 分钟
4. 倒掉蒸出的水，铺葱姜丝，淋蒸鱼豉油
5. 浇热油激出香味

---

## 川湘重口味菜

### 18. 辣子鸡

- **主料：** 鸡腿肉/鸡翅 400g
- **配料：** 干辣椒一大把、花椒、蒜、姜、葱
- **调料：** 料酒、生抽、盐、白糖、淀粉
- **难度：** ⭐⭐ | **耗时：** 25 分钟 | **份量：** 2~3 人

**做法：**
1. 鸡肉切小块，加盐、料酒、生抽、淀粉腌 15 分钟
2. 油温六成热（筷子入油起小泡），下鸡块炸至金黄捞出
3. 锅留底油，小火煸香干辣椒段和花椒（不要炒糊）
4. 下鸡块大火翻炒，加少许糖、盐
5. 撒葱花和白芝麻出锅

---

### 19. 水煮肉片

- **主料：** 里脊肉/猪肉 300g
- **配料：** 豆芽、生菜/油麦菜、蒜末、葱花
- **调料：** 豆瓣酱、干辣椒、花椒、料酒、生抽、淀粉
- **难度：** ⭐⭐ | **耗时：** 20 分钟 | **份量：** 2~3 人

**做法：**
1. 肉切薄片，加盐、料酒、蛋清、淀粉抓匀腌 10 分钟
2. 蔬菜焯水铺在碗底
3. 锅中油烧热，炒香豆瓣酱出红油，加蒜末、姜末
4. 加水（或高汤）烧开，下肉片拨散，煮至变色（约 1 分钟）
5. 连汤倒在蔬菜上
6. 面上铺蒜末、干辣椒段、花椒，浇一勺滚油（滋啦）

---

### 20. 剁椒鱼头

- **主料：** 鳙鱼头 1 个（胖头鱼）
- **配料：** 剁椒 3 大勺、姜蒜末、葱花
- **调料：** 料酒、生抽、盐
- **难度：** ⭐⭐ | **耗时：** 25 分钟 | **份量：** 2~3 人

**做法：**
1. 鱼头洗净对半剖开，抹盐和料酒腌 10 分钟
2. 盘底铺姜片葱段，放鱼头（切面朝上）
3. 鱼头上铺满剁椒，撒姜蒜末
4. 水开后大火蒸 12~15 分钟
5. 撒葱花，浇热油

---

## 菜品索引（按主料快查）

| 主料 | 可做菜品 |
|------|---------|
| 五花肉 | 红烧肉 |
| 鸡翅 | 可乐鸡翅 |
| 鸡蛋 + 西红柿 | 番茄炒蛋、西红柿蛋花汤 |
| 土豆 | 酸辣土豆丝 |
| 西兰花 | 蒜蓉西兰花 |
| 排骨 | 红烧排骨 |
| 豆腐 + 猪肉 | 麻婆豆腐 |
| 空心菜 | 清炒空心菜 |
| 鲈鱼 | 清蒸鲈鱼 |
| 冬瓜 + 猪肉 | 冬瓜丸子汤 |
| 虾/虾仁 | 蒜蓉炒虾仁、白灼虾 |
| 黄瓜 | 凉拌黄瓜 |
| 肥牛 + 金针菇 | 肥牛金针菇卷 |
| 鸡胸肉 | 水煮鸡胸肉沙拉 |
| 鳕鱼 | 清蒸鳕鱼 |
| 鸡腿/鸡肉 | 辣子鸡 |
| 里脊肉/猪肉 | 水煮肉片 |
| 鳙鱼 | 剁椒鱼头 |

## 菜品风格标签

| 风格 | 菜品编号 |
|------|---------|
| 家常 | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 |
| 快手10分钟 | 3, 4, 5, 8, 11, 12, 13, 14 |
| 清淡减脂 | 5, 14, 15, 16, 17 |
| 川湘重口 | 4, 7, 18, 19, 20 |

FILE:references/ingredients.md
# 食材数据库

所有支持的食材分类和列表。匹配用户输入时支持别名和模糊匹配。

## 肉类（20 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| M01 | 猪肉 | 瘦肉、前腿肉 | 炒、炖、蒸 | 通用肉类 |
| M02 | 五花肉 | 三层肉 | 红烧、煎、烤 | 肥瘦相间，红烧首选 |
| M03 | 排骨 | 肋排、小排 | 红烧、炖、蒸、糖醋 | 需焯水去腥 |
| M04 | 猪蹄 | 猪脚、猪手 | 红烧、炖、卤 | 富含胶原蛋白，炖煮时间长 |
| M05 | 里脊肉 | 猪里脊、小里脊 | 炒、炸、滑溜 | 嫩，适合快炒 |
| M06 | 猪肝 | — | 炒、卤、煮汤 | 需充分清洗，补铁 |
| M07 | 猪大肠 | 肥肠 | 卤、炒、干锅 | 需反复清洗去异味 |
| M08 | 牛肉 | — | 炒、炖、卤 | 纤维粗，需切逆纹 |
| M09 | 牛腩 | — | 炖、红烧、咖喱 | 适合慢炖，越炖越烂 |
| M10 | 牛腱子 | 牛腱 | 卤、炖 | 口感筋道，适合卤制 |
| M11 | 肥牛 | 肥牛卷、肥牛片 | 涮、炒、煮 | 薄片，快熟 |
| M12 | 羊肉 | — | 炖、涮、烤、炒 | 配萝卜去膻味 |
| M13 | 羊排 | — | 烤、炖、红焖 | 带骨更香 |
| M14 | 鸡肉 | 整鸡、鸡块 | 炖、蒸、炒、煮 | 万能蛋白质 |
| M15 | 鸡腿 | 琵琶腿、大鸡腿 | 红烧、烤、卤、炸 | 肉质嫩多汁 |
| M16 | 鸡翅 | 鸡翅中、翅中 | 可乐鸡翅、烤、炸、卤 | 需划刀方便入味 |
| M17 | 鸡爪 | 凤爪 | 卤、炖、泡椒 | 富含胶原蛋白 |
| M18 | 鸡胸肉 | 鸡胸 | 煎、炒、水煮 | 高蛋白低脂，减脂首选 |
| M19 | 鸭肉 | 整鸭、鸭块 | 炖、卤、烤 | 配啤酒或老鸭汤 |
| M20 | 鸭翅 | — | 卤、烤 | 适合卤制入味 |

## 水产海鲜（20 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| S01 | 草鱼 | — | 水煮、红烧、清蒸 | 刺多但肉厚 |
| S02 | 鲫鱼 | — | 煲汤、红烧 | 煲汤奶白色，鲜美 |
| S03 | 鲈鱼 | 海鲈鱼 | 清蒸、红烧 | 刺少肉嫩，清蒸首选 |
| S04 | 黑鱼 | 乌鱼、生鱼 | 酸菜鱼、煲汤 | 肉质紧实 |
| S05 | 黄骨鱼 | 黄辣丁、黄颡鱼 | 煲汤、红烧 | 肉嫩无小刺 |
| S06 | 鲢鱼 | 白鲢 | 水煮、炖 | 经济实惠 |
| S07 | 鳙鱼 | 胖头鱼、花鲢 | 剁椒鱼头、煲汤 | 鱼头大，胶质丰富 |
| S08 | 虾 | 基围虾、大虾、明虾 | 白灼、炒、蒸 | 蛋白质高，快熟 |
| S09 | 小龙虾 | 龙虾 | 蒜蓉、麻辣、十三香 | 需充分刷洗 |
| S10 | 螃蟹 | 大闸蟹、梭子蟹 | 清蒸、炒年糕 | 秋天最肥美 |
| S11 | 花甲 | 蛤蜊、蚬子 | 炒、煮汤、蒸 | 需提前吐沙 |
| S12 | 扇贝 | — | 蒜蓉粉丝蒸 | 蒜蓉蒸最经典 |
| S13 | 生蚝 | 牡蛎、海蛎子 | 蒜蓉烤、煎蛋 | 锌含量高 |
| S14 | 鱿鱼 | — | 炒、烤、干锅 | 需打花刀 |
| S15 | 墨鱼 | 乌贼 | 炒、炖汤 | 可取墨囊 |
| S16 | 八爪鱼 | 章鱼、小章鱼 | 炒、烤、凉拌 | 焯水后口感好 |
| S17 | 带鱼 | — | 煎、红烧、糖醋 | 需去内脏和黑膜 |
| S18 | 黄花鱼 | 黄鱼 | 红烧、煎、炖 | 肉嫩味鲜 |
| S19 | 鳕鱼 | — | 煎、蒸、烤 | 肉质细嫩，无刺 |
| S20 | 三文鱼 | 鲑鱼 | 刺身、煎、烤 | 生食需确保新鲜度 |

## 蛋类 & 豆制品（10 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| E01 | 鸡蛋 | 蛋 | 炒、煎、蒸、煮 | 万能食材 |
| E02 | 鸭蛋 | — | 腌制、煎 | 咸鸭蛋更常见 |
| E03 | 鹅蛋 | — | 煎、蒸 | 个头大，蛋香浓 |
| E04 | 鹌鹑蛋 | — | 卤、煮、炖 | 小巧玲珑 |
| E05 | 豆腐 | 老豆腐、北豆腐 | 红烧、煎、炖 | 质地较硬，适合煎炒 |
| E06 | 嫩豆腐 | 内酯豆腐、南豆腐 | 蒸、煮汤、凉拌 | 质地软嫩 |
| E07 | 冻豆腐 | — | 炖、火锅、煮 | 口感像海绵，吸汁 |
| E08 | 豆干 | 豆腐干、香干 | 炒、卤、凉拌 | 口感紧实 |
| E09 | 千张 | 豆皮、百叶 | 凉拌、炒、卷 | 薄如纸张 |
| E10 | 腐竹 | — | 炖、凉拌、炒 | 需提前泡发 |

## 蔬菜（31 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| V01 | 白菜 | 大白菜 | 炒、炖、煮、腌 | 百搭蔬菜 |
| V02 | 娃娃菜 | 小白菜 | 蒜蓉、煮汤、炒 | 比大白菜更嫩甜 |
| V03 | 菠菜 | — | 炒、煮汤、凉拌 | 焯水去草酸 |
| V04 | 生菜 | — | 生吃、蒜蓉、涮 | 口感脆嫩 |
| V05 | 油麦菜 | — | 蒜蓉、炒 | 类似生菜但更长 |
| V06 | 空心菜 | 通菜、蕹菜 | 清炒、蒜蓉 | 大火快炒防变黑 |
| V07 | 韭菜 | — | 炒蛋、饺子馅 | 香味浓，快熟 |
| V08 | 芹菜 | 西芹 | 炒、凉拌 | 可去筋口感更好 |
| V09 | 香菜 | 芫荽 | 配菜、凉拌 | 提味点缀用 |
| V10 | 茼蒿 | — | 清炒、涮火锅 | 火锅必备蔬菜 |
| V11 | 西兰花 | 绿花菜 | 蒜蓉、白灼、炒 | 焯水后更翠绿 |
| V12 | 菜花 | 花菜、白花菜 | 干锅、炒、烤 | 掰小朵更入味 |
| V13 | 黄瓜 | 青瓜 | 凉拌、炒 | 拍碎比切更入味 |
| V14 | 冬瓜 | — | 炖汤、红烧 | 利尿消肿 |
| V15 | 南瓜 | — | 蒸、煮粥、炒 | 甜糯口感 |
| V16 | 丝瓜 | — | 炒蛋、煮汤 | 去皮后快炒 |
| V17 | 苦瓜 | 凉瓜 | 炒蛋、凉拌 | 焯水可减苦味 |
| V18 | 茄子 | — | 红烧、蒸、烤 | 吸油大户，可先蒸 |
| V19 | 西红柿 | 番茄 | 炒蛋、煮汤、酱 | 万能配菜 |
| V20 | 土豆 | 马铃薯 | 炒丝、炖、焖 | 切丝泡水防变色 |
| V21 | 山药 | 淮山 | 炒、炖、蒸 | 去皮戴手套防痒 |
| V22 | 红薯 | 地瓜、番薯 | 蒸、烤、煮粥 | 软糯香甜 |
| V23 | 胡萝卜 | 红萝卜 | 炒、炖、煮 | 过油更易吸收 |
| V24 | 白萝卜 | — | 炖、煮汤、凉拌 | 冬吃萝卜，清甜 |
| V25 | 洋葱 | — | 炒、配菜、凉拌 | 切丝泡水减辣 |
| V26 | 大蒜 | 蒜头 | 调味、蒜蓉 | 百搭调味 |
| V27 | 生姜 | 姜 | 调味、去腥 | 肉类必备 |
| V28 | 青椒 | 柿子椒 | 炒肉、配菜 | 微辣，口感脆 |
| V29 | 红椒 | 彩椒 | 炒、配色 | 甜脆，提色 |
| V30 | 莲藕 | 藕 | 炒、炖、凉拌 | 脆藕炒，粉藕炖 |
| V31 | 金针菇 | — | 烤、涮、炒 | 需去根部 |

## 干货 & 菌菇（10 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| D01 | 香菇 | 冬菇 | 炒、炖、蒸 | 干香菇需泡发，水可做汤底 |
| D02 | 木耳 | 黑木耳 | 炒、凉拌 | 干木耳泡发后体积增大数倍 |
| D03 | 银耳 | 白木耳 | 甜汤、炖 | 需泡发撕小朵 |
| D04 | 海带 | 昆布 | 炖、凉拌、煮汤 | 需提前泡软 |
| D05 | 紫菜 | — | 煮汤、包饭 | 即食型可直接用 |
| D06 | 腐竹 | — | 炖、凉拌、炒 | 需提前泡发 2~4 小时 |
| D07 | 粉丝 | 龙口粉丝 | 炖、煮、炒 | 热水泡软即可 |
| D08 | 粉条 | 红薯粉条 | 炖、炒 | 口感比粉丝更筋道 |
| D09 | 黄花菜 | 金针菜 | 炒、炖、煮汤 | 干的需泡发，鲜的需焯水 |
| D10 | 茶树菇 | — | 炒、炖 | 干的需泡发，菌香浓 |

## 主食杂粮（10 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| G01 | 大米 | 白米 | 蒸饭、煮粥 | 主食首选 |
| G02 | 小米 | 黄小米 | 煮粥 | 养胃 |
| G03 | 糯米 | 江米 | 粽子、糯米饭、汤圆 | 黏性大 |
| G04 | 玉米 | — | 煮、蒸、炒 | 甜玉米/糯玉米 |
| G05 | 面条 | 挂面、手擀面 | 煮、炒、拌 | 快手主食 |
| G06 | 馒头 | — | 蒸、煎 | 配菜搭档 |
| G07 | 面粉 | 中筋粉 | 包饺子、煎饼、面疙瘩 | 万能主食原料 |
| G08 | 绿豆 | — | 煮汤、煮粥 | 夏天消暑 |
| G09 | 红豆 | 赤小豆 | 煮粥、煮汤 | 需提前泡 |
| G10 | 花生 | — | 炒、煮、炖 | 配菜或零嘴 |

## 默认视为已有的调味料

以下调料在推荐菜谱时默认用户家中已有，不需要额外确认：

- **基础调味：** 盐、白糖、鸡精/味精
- **酱油类：** 生抽、老抽、蚝油
- **酒醋类：** 料酒、米醋/白醋、陈醋
- **油脂类：** 食用油、芝麻油/香油
- **辛香料：** 干辣椒、花椒、八角、桂皮、香叶
- **酱料类：** 豆瓣酱、甜面酱、番茄酱
- **粉类：** 淀粉/生粉、胡椒粉、五香粉、十三香
- **其他：** 葱、蒜、姜（也列在蔬菜中，但作为调味时默认有）

FILE:evals/evals.json
{
  "skill_name": "daily-menu",
  "evals": [
    {
      "id": 1,
      "prompt": "我冰箱里有鸡翅和土豆，今晚做什么菜好？",
      "expected_output": "推荐可乐鸡翅和酸辣土豆丝，给出详细做法和备菜清单",
      "expectations": [
        "推荐的菜品使用了鸡翅和土豆",
        "给出了具体的烹饪步骤和时间",
        "包含备菜清单",
        "菜品荤素搭配"
      ]
    },
    {
      "id": 2,
      "prompt": "家里有五花肉和冬瓜，3个人吃饭，帮我安排一下",
      "expected_output": "推荐红烧肉和冬瓜丸子汤等菜品，考虑3人份量",
      "expectations": [
        "推荐的菜用到了五花肉和冬瓜",
        "考虑了3人的份量",
        "给出了烹饪时间线建议"
      ]
    },
    {
      "id": 3,
      "prompt": "我在减肥，有鸡胸肉和西兰花，推荐减脂餐",
      "expected_output": "推荐清淡减脂菜品如水煮鸡胸肉沙拉和蒜蓉西兰花",
      "expectations": [
        "推荐的菜符合减脂风格",
        "给出了热量估算",
        "烹饪方式清淡（蒸、煮、白灼等）"
      ]
    },
    {
      "id": 4,
      "prompt": "只有10分钟，虾和黄瓜能做啥？",
      "expected_output": "推荐蒜蓉炒虾仁和凉拌黄瓜等快手菜",
      "expectations": [
        "推荐的菜品都在10分钟以内",
        "用到了虾和黄瓜",
        "做法简单快捷"
      ]
    },
    {
      "id": 5,
      "prompt": "今天想吃辣的，家里有里脊肉和豆腐",
      "expected_output": "推荐川湘重口味菜品如水煮肉片和麻婆豆腐",
      "expectations": [
        "推荐的菜品是重口味/川湘风格",
        "用到了里脊肉和豆腐",
        "包含辣椒/花椒等调料"
      ]
    }
  ]
}

---
name: daily-menu
description: >-
  生成今日菜单推荐。根据用户手头的食材、口味偏好、人数和烹饪时间，
  从内置食材库和菜谱库中智能匹配，输出完整的菜单方案和分步烹饪指南。
  当用户提到"今天吃什么""做什么菜""菜单""菜谱推荐""晚饭吃啥"等意图时触发。
---

# 今日菜单生成器

根据用户现有食材、口味偏好、就餐人数和可用时间，生成个性化菜单推荐和烹饪指南。

## 工作流程

### 第一步：了解用户需求

通过简短对话收集以下信息（缺失项用合理默认值）：

| 信息项 | 默认值 | 说明 |
|--------|--------|------|
| 手头食材 | — | **必问**，至少确认 1~3 种主要食材 |
| 就餐人数 | 2 人 | 影响份量建议 |
| 口味偏好 | 家常 | 家常 / 清淡减脂 / 川湘重口 / 快手10分钟 |
| 可用时间 | 60 分钟 | 影响菜品复杂度 |
| 忌口/过敏 | 无 | 如有则排除相关食材 |
| 菜品数量 | 2~4 道 | 根据人数自动建议 |

**对话原则：**
- 不要一次问太多问题，最核心的是「你手头有什么食材？」
- 如果用户只说了食材，其他用默认值直接推荐
- 语气轻松友好，像朋友聊天一样

### 第二步：匹配菜谱

1. 读取 `references/ingredients.md` 获取完整食材分类
2. 读取 `references/recipes.md` 获取菜谱库
3. 根据用户提供的食材，从菜谱库中匹配可做的菜品
4. 考虑荤素搭配、营养均衡、烹饪难度

**匹配规则：**
- 主料必须匹配（用户手头有的食材）
- 常见调料（盐、酱油、醋、糖、料酒、蚝油等）默认家里有，不需要确认
- 优先推荐主料完全匹配的菜，其次推荐只差 1~2 种配料的菜
- 如果用户食材能做的菜不够，可以建议额外采购少量食材

### 第三步：输出菜单

使用以下格式输出：

```
## 🍽️ 今日菜单推荐

**就餐人数：** X 人 | **预计用时：** X 分钟 | **风格：** XXX

---

### 1. 菜名 ⭐
> 一句话点评这道菜的特点

**食材：**
- 主料：XXX
- 配料：XXX
- 调料：XXX

**做法：**
1. 第一步（附时间和火候）
2. 第二步
3. ...

**小贴士：** 实用烹饪技巧

---

### 2. 菜名
（同上格式）

---

## 📋 备菜清单

把所有菜需要的食材汇总，方便一次性准备：

| 分类 | 食材 | 用量 | 处理方式 |
|------|------|------|----------|
| 肉类 | ... | ... | ... |
| 蔬菜 | ... | ... | ... |

## ⏱️ 烹饪时间线

建议的做菜顺序和并行操作：
1. 先做 XX（耗时最长的先开始）
2. 在等待的同时准备 XX
3. 最后快炒 XX
```

### 第四步：后续互动

菜单输出后，主动询问：
- 「要不要换掉某道菜？」
- 「要不要看更详细的某道菜做法？」
- 「还想加个汤/凉菜吗？」

## 口味风格指南

### 家常风格（默认）
- 红烧、清炒、炖煮为主
- 调味适中，老少皆宜
- 代表菜：红烧肉、番茄炒蛋、清炒时蔬

### 清淡减脂
- 少油少盐，以蒸、煮、白灼为主
- 多蔬菜，蛋白质优先选鸡胸肉/鱼/虾/豆腐
- 减少碳水，避免油炸
- 标注估算热量

### 快手 10 分钟
- 只推荐炒、拌、煮等快速烹饪方式
- 食材处理简单（切丝切片为主）
- 每道菜控制在 10 分钟以内

### 川湘重口味
- 麻辣鲜香，重油重味
- 豆瓣酱、辣椒、花椒、剁椒等调料
- 代表菜：麻婆豆腐、辣子鸡、酸辣土豆丝

## 重要原则

1. **实用优先**：做法描述要具体到火候、时间、用量，不要含糊
2. **荤素搭配**：2 道菜以上时确保有荤有素
3. **难度递进**：多道菜时从简到难排列
4. **时间合理**：给出的总用时要考虑并行操作
5. **食材不浪费**：尽量用完用户提到的食材
6. **安全第一**：涉及生食（如三文鱼）要提醒新鲜度要求

FILE:scripts/generate_menu.py
#!/usr/bin/env python3
"""
今日菜单生成器 - 根据用户食材自动匹配菜谱并生成菜单方案。

用法:
    python scripts/generate_menu.py --ingredients "鸡翅,土豆,西红柿,鸡蛋"
    python scripts/generate_menu.py --ingredients "五花肉,冬瓜" --people 4 --style 家常
    python scripts/generate_menu.py --ingredients "鸡胸肉,黄瓜,西兰花" --style 清淡减脂
    python scripts/generate_menu.py --ingredients "里脊肉,豆腐" --style 川湘重口 --count 3
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path
from typing import Optional


# ── 菜谱数据 ──────────────────────────────────────────────────────────

RECIPES = [
    {
        "id": 1,
        "name": "红烧肉",
        "main_ingredients": ["五花肉"],
        "styles": ["家常"],
        "difficulty": 2,
        "time_minutes": 50,
        "serves": "2~3人",
    },
    {
        "id": 2,
        "name": "可乐鸡翅",
        "main_ingredients": ["鸡翅"],
        "styles": ["家常"],
        "difficulty": 1,
        "time_minutes": 25,
        "serves": "2人",
    },
    {
        "id": 3,
        "name": "番茄炒蛋",
        "main_ingredients": ["西红柿", "鸡蛋"],
        "styles": ["家常", "快手10分钟"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
    },
    {
        "id": 4,
        "name": "酸辣土豆丝",
        "main_ingredients": ["土豆"],
        "styles": ["家常", "快手10分钟", "川湘重口"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
    },
    {
        "id": 5,
        "name": "蒜蓉西兰花",
        "main_ingredients": ["西兰花"],
        "styles": ["家常", "快手10分钟", "清淡减脂"],
        "difficulty": 1,
        "time_minutes": 8,
        "serves": "2人",
    },
    {
        "id": 6,
        "name": "红烧排骨",
        "main_ingredients": ["排骨"],
        "styles": ["家常"],
        "difficulty": 2,
        "time_minutes": 60,
        "serves": "2~3人",
    },
    {
        "id": 7,
        "name": "麻婆豆腐",
        "main_ingredients": ["豆腐", "猪肉"],
        "styles": ["家常", "川湘重口"],
        "difficulty": 2,
        "time_minutes": 15,
        "serves": "2人",
    },
    {
        "id": 8,
        "name": "清炒空心菜",
        "main_ingredients": ["空心菜"],
        "styles": ["家常", "快手10分钟"],
        "difficulty": 1,
        "time_minutes": 5,
        "serves": "2人",
    },
    {
        "id": 9,
        "name": "清蒸鲈鱼",
        "main_ingredients": ["鲈鱼"],
        "styles": ["家常"],
        "difficulty": 2,
        "time_minutes": 20,
        "serves": "2~3人",
    },
    {
        "id": 10,
        "name": "冬瓜丸子汤",
        "main_ingredients": ["冬瓜", "猪肉"],
        "styles": ["家常"],
        "difficulty": 1,
        "time_minutes": 25,
        "serves": "2~3人",
    },
    {
        "id": 11,
        "name": "蒜蓉炒虾仁",
        "main_ingredients": ["虾"],
        "styles": ["快手10分钟"],
        "difficulty": 1,
        "time_minutes": 8,
        "serves": "2人",
    },
    {
        "id": 12,
        "name": "凉拌黄瓜",
        "main_ingredients": ["黄瓜"],
        "styles": ["快手10分钟"],
        "difficulty": 1,
        "time_minutes": 5,
        "serves": "2人",
    },
    {
        "id": 13,
        "name": "肥牛金针菇卷",
        "main_ingredients": ["肥牛", "金针菇"],
        "styles": ["快手10分钟"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
    },
    {
        "id": 14,
        "name": "西红柿蛋花汤",
        "main_ingredients": ["西红柿", "鸡蛋"],
        "styles": ["快手10分钟", "清淡减脂"],
        "difficulty": 1,
        "time_minutes": 8,
        "serves": "2人",
    },
    {
        "id": 15,
        "name": "白灼虾",
        "main_ingredients": ["虾"],
        "styles": ["清淡减脂"],
        "difficulty": 1,
        "time_minutes": 10,
        "serves": "2人",
        "calories": "~200kcal",
    },
    {
        "id": 16,
        "name": "水煮鸡胸肉沙拉",
        "main_ingredients": ["鸡胸肉"],
        "styles": ["清淡减脂"],
        "difficulty": 1,
        "time_minutes": 15,
        "serves": "1人",
        "calories": "~300kcal",
    },
    {
        "id": 17,
        "name": "清蒸鳕鱼",
        "main_ingredients": ["鳕鱼"],
        "styles": ["清淡减脂"],
        "difficulty": 1,
        "time_minutes": 15,
        "serves": "1人",
        "calories": "~180kcal",
    },
    {
        "id": 18,
        "name": "辣子鸡",
        "main_ingredients": ["鸡腿", "鸡翅", "鸡肉"],
        "styles": ["川湘重口"],
        "difficulty": 2,
        "time_minutes": 25,
        "serves": "2~3人",
    },
    {
        "id": 19,
        "name": "水煮肉片",
        "main_ingredients": ["里脊肉", "猪肉"],
        "styles": ["川湘重口"],
        "difficulty": 2,
        "time_minutes": 20,
        "serves": "2~3人",
    },
    {
        "id": 20,
        "name": "剁椒鱼头",
        "main_ingredients": ["鳙鱼"],
        "styles": ["川湘重口"],
        "difficulty": 2,
        "time_minutes": 25,
        "serves": "2~3人",
    },
]

# 食材别名映射 → 标准名
ALIASES = {
    "番茄": "西红柿",
    "蕃茄": "西红柿",
    "洋柿子": "西红柿",
    "瘦肉": "猪肉",
    "前腿肉": "猪肉",
    "肉末": "猪肉",
    "肉馅": "猪肉",
    "猪里脊": "里脊肉",
    "小里脊": "里脊肉",
    "肥肠": "猪大肠",
    "猪手": "猪蹄",
    "猪脚": "猪蹄",
    "牛腱": "牛腱子",
    "肥牛卷": "肥牛",
    "肥牛片": "肥牛",
    "琵琶腿": "鸡腿",
    "大鸡腿": "鸡腿",
    "鸡翅中": "鸡翅",
    "翅中": "鸡翅",
    "凤爪": "鸡爪",
    "鸡胸": "鸡胸肉",
    "海鲈鱼": "鲈鱼",
    "基围虾": "虾",
    "大虾": "虾",
    "明虾": "虾",
    "虾仁": "虾",
    "龙虾": "小龙虾",
    "蛤蜊": "花甲",
    "蚬子": "花甲",
    "牡蛎": "生蚝",
    "海蛎子": "生蚝",
    "乌贼": "墨鱼",
    "章鱼": "八爪鱼",
    "小章鱼": "八爪鱼",
    "黄鱼": "黄花鱼",
    "鲑鱼": "三文鱼",
    "胖头鱼": "鳙鱼",
    "花鲢": "鳙鱼",
    "蛋": "鸡蛋",
    "老豆腐": "豆腐",
    "北豆腐": "豆腐",
    "内酯豆腐": "嫩豆腐",
    "南豆腐": "嫩豆腐",
    "豆腐干": "豆干",
    "香干": "豆干",
    "豆皮": "千张",
    "百叶": "千张",
    "大白菜": "白菜",
    "小白菜": "娃娃菜",
    "通菜": "空心菜",
    "蕹菜": "空心菜",
    "西芹": "芹菜",
    "芫荽": "香菜",
    "绿花菜": "西兰花",
    "花菜": "菜花",
    "白花菜": "菜花",
    "青瓜": "黄瓜",
    "凉瓜": "苦瓜",
    "马铃薯": "土豆",
    "淮山": "山药",
    "地瓜": "红薯",
    "番薯": "红薯",
    "红萝卜": "胡萝卜",
    "蒜头": "大蒜",
    "蒜": "大蒜",
    "姜": "生姜",
    "柿子椒": "青椒",
    "彩椒": "红椒",
    "藕": "莲藕",
    "冬菇": "香菇",
    "黑木耳": "木耳",
    "白木耳": "银耳",
    "昆布": "海带",
    "龙口粉丝": "粉丝",
    "红薯粉条": "粉条",
    "金针菜": "黄花菜",
    "白米": "大米",
    "黄小米": "小米",
    "江米": "糯米",
    "挂面": "面条",
    "手擀面": "面条",
    "中筋粉": "面粉",
    "赤小豆": "红豆",
}


def normalize_ingredient(name: str) -> str:
    """将用户输入的食材名标准化。"""
    name = name.strip()
    return ALIASES.get(name, name)


def match_recipes(user_ingredients: list[str], style: str | None = None) -> list[dict]:
    """根据用户食材和风格偏好匹配菜谱。

    返回按匹配度排序的菜谱列表，每个菜谱附带 match_score。
    """
    normalized = [normalize_ingredient(i) for i in user_ingredients]
    results = []

    for recipe in RECIPES:
        # 风格过滤
        if style and style not in recipe["styles"]:
            continue

        # 计算主料匹配度
        required = recipe["main_ingredients"]
        matched = sum(1 for r in required if r in normalized)

        if matched == 0:
            continue

        score = matched / len(required)  # 1.0 = 完全匹配
        missing = [r for r in required if r not in normalized]

        results.append({
            **recipe,
            "match_score": score,
            "missing_ingredients": missing,
        })

    # 按匹配度降序、难度升序排列
    results.sort(key=lambda x: (-x["match_score"], x["difficulty"]))
    return results


def categorize_ingredient(name: str) -> str:
    """判断食材类别。"""
    meat = {"猪肉", "五花肉", "排骨", "猪蹄", "里脊肉", "猪肝", "猪大肠",
            "牛肉", "牛腩", "牛腱子", "肥牛", "羊肉", "羊排",
            "鸡肉", "鸡腿", "鸡翅", "鸡爪", "鸡胸肉", "鸭肉", "鸭翅"}
    seafood = {"草鱼", "鲫鱼", "鲈鱼", "黑鱼", "黄骨鱼", "鲢鱼", "鳙鱼",
               "虾", "小龙虾", "螃蟹", "花甲", "扇贝", "生蚝",
               "鱿鱼", "墨鱼", "八爪鱼", "带鱼", "黄花鱼", "鳕鱼", "三文鱼"}
    egg_tofu = {"鸡蛋", "鸭蛋", "鹅蛋", "鹌鹑蛋",
                "豆腐", "嫩豆腐", "冻豆腐", "豆干", "千张", "腐竹"}
    vegs = {"白菜", "娃娃菜", "菠菜", "生菜", "油麦菜", "空心菜", "韭菜",
            "芹菜", "香菜", "茼蒿", "西兰花", "菜花", "黄瓜", "冬瓜",
            "南瓜", "丝瓜", "苦瓜", "茄子", "西红柿", "土豆", "山药",
            "红薯", "胡萝卜", "白萝卜", "洋葱", "大蒜", "生姜",
            "青椒", "红椒", "莲藕", "金针菇"}
    dried = {"香菇", "木耳", "银耳", "海带", "紫菜", "粉丝", "粉条", "黄花菜", "茶树菇"}
    staple = {"大米", "小米", "糯米", "玉米", "面条", "馒头", "面粉", "绿豆", "红豆", "花生"}

    n = normalize_ingredient(name)
    if n in meat:
        return "肉类"
    if n in seafood:
        return "水产海鲜"
    if n in egg_tofu:
        return "蛋类/豆制品"
    if n in vegs:
        return "蔬菜"
    if n in dried:
        return "干货/菌菇"
    if n in staple:
        return "主食杂粮"
    return "其他"


def generate_menu(
    user_ingredients: list[str],
    people: int = 2,
    style: str | None = None,
    count: int | None = None,
    time_limit: int | None = None,
) -> dict:
    """生成完整菜单方案。

    Args:
        user_ingredients: 用户手头的食材列表
        people: 就餐人数
        style: 口味偏好（家常/清淡减脂/快手10分钟/川湘重口）
        count: 期望菜品数量
        time_limit: 可用烹饪时间（分钟）

    Returns:
        包含推荐菜品、备菜清单、时间线的字典
    """
    if count is None:
        count = min(max(2, people), 4)  # 2~4 道菜

    # 匹配菜谱
    matched = match_recipes(user_ingredients, style)

    if not matched:
        return {
            "success": False,
            "message": "抱歉，根据你提供的食材暂时没有匹配的菜谱。",
            "user_ingredients": user_ingredients,
            "suggestions": "试试提供更多食材，或者换个口味风格？",
        }

    # 选菜策略：荤素搭配
    selected = []
    has_meat = False
    has_veg = False

    for recipe in matched:
        if len(selected) >= count:
            break

        # 时间限制
        if time_limit and recipe["time_minutes"] > time_limit:
            continue

        # 判断荤素
        is_meat = any(
            categorize_ingredient(i) in ("肉类", "水产海鲜")
            for i in recipe["main_ingredients"]
        )

        selected.append({**recipe, "is_meat": is_meat})
        if is_meat:
            has_meat = True
        else:
            has_veg = True

    # 如果只有荤或只有素，且还有余量，补充
    if len(selected) < count and selected:
        for recipe in matched:
            if recipe["id"] in [s["id"] for s in selected]:
                continue
            if len(selected) >= count:
                break

            is_meat = any(
                categorize_ingredient(i) in ("肉类", "水产海鲜")
                for i in recipe["main_ingredients"]
            )

            if (not has_veg and not is_meat) or (not has_meat and is_meat):
                selected.append({**recipe, "is_meat": is_meat})
                if is_meat:
                    has_meat = True
                else:
                    has_veg = True

    # 按耗时从长到短排列（烹饪时间线用）
    selected.sort(key=lambda x: -x["time_minutes"])

    total_time = max(r["time_minutes"] for r in selected) if selected else 0

    # 汇总食材清单
    all_ingredients = {}
    for recipe in selected:
        for ing in recipe["main_ingredients"]:
            cat = categorize_ingredient(ing)
            if cat not in all_ingredients:
                all_ingredients[cat] = []
            if ing not in all_ingredients[cat]:
                all_ingredients[cat].append(ing)

    return {
        "success": True,
        "people": people,
        "style": style or "家常",
        "estimated_time": total_time,
        "dishes": [
            {
                "id": r["id"],
                "name": r["name"],
                "difficulty": r["difficulty"],
                "time_minutes": r["time_minutes"],
                "serves": r["serves"],
                "match_score": r["match_score"],
                "missing_ingredients": r.get("missing_ingredients", []),
                "calories": r.get("calories"),
            }
            for r in selected
        ],
        "ingredient_summary": all_ingredients,
        "cooking_timeline": [
            {
                "order": i + 1,
                "dish": r["name"],
                "time_minutes": r["time_minutes"],
                "tip": "先开始（耗时最长）" if i == 0 else (
                    "可与上一道并行准备" if r["time_minutes"] <= 15 else "等前面的炖上后开始"
                ),
            }
            for i, r in enumerate(selected)
        ],
    }


def main():
    parser = argparse.ArgumentParser(
        description="今日菜单生成器 - 根据食材推荐菜谱"
    )
    parser.add_argument(
        "--ingredients", "-i",
        required=True,
        help="用户手头的食材，逗号分隔，如 '鸡翅,土豆,西红柿,鸡蛋'",
    )
    parser.add_argument(
        "--people", "-p",
        type=int,
        default=2,
        help="就餐人数 (默认 2)",
    )
    parser.add_argument(
        "--style", "-s",
        choices=["家常", "清淡减脂", "快手10分钟", "川湘重口"],
        default=None,
        help="口味风格偏好",
    )
    parser.add_argument(
        "--count", "-c",
        type=int,
        default=None,
        help="期望菜品数量 (默认根据人数自动)",
    )
    parser.add_argument(
        "--time", "-t",
        type=int,
        default=None,
        help="可用烹饪时间（分钟）",
    )
    parser.add_argument(
        "--output", "-o",
        default=None,
        help="输出 JSON 文件路径（默认输出到 stdout）",
    )

    args = parser.parse_args()

    ingredients = [i.strip() for i in args.ingredients.split(",") if i.strip()]

    result = generate_menu(
        user_ingredients=ingredients,
        people=args.people,
        style=args.style,
        count=args.count,
        time_limit=args.time,
    )

    output = json.dumps(result, ensure_ascii=False, indent=2)

    if args.output:
        Path(args.output).write_text(output, encoding="utf-8")
        print(f"菜单已保存到 {args.output}")
    else:
        print(output)


if __name__ == "__main__":
    main()

FILE:references/recipes.md
# 菜谱数据库

内置经典家常菜谱，按风格分类。每道菜标注主料、难度、耗时和详细做法。

---

## 经典家常菜

### 1. 红烧肉 ⭐

- **主料：** 五花肉 500g
- **配料：** 葱、姜
- **调料：** 冰糖/白糖、生抽、老抽、料酒
- **难度：** ⭐⭐ | **耗时：** 50 分钟 | **份量：** 2~3 人

**做法：**
1. 五花肉切 2cm 方块，冷水下锅焯水 3 分钟，捞出洗净浮沫
2. 锅中少许油，放冰糖小火炒至枣红色起大泡（糖色）
3. 下五花肉快速翻炒上色，每块肉均匀裹上糖色
4. 加葱段、姜片、料酒 2 勺、生抽 2 勺、老抽 1 勺翻炒
5. 加开水没过肉，大火烧开后转小火炖 40 分钟
6. 最后大火收汁，汁浓亮即可

**小贴士：** 全程不要加盐，生抽和老抽的咸度足够。加开水而非冷水，肉不会发柴。

---

### 2. 可乐鸡翅

- **主料：** 鸡翅 8~10 个
- **配料：** 可乐 1 罐（330ml）、姜片
- **调料：** 生抽、料酒
- **难度：** ⭐ | **耗时：** 25 分钟 | **份量：** 2 人

**做法：**
1. 鸡翅两面各划 2~3 刀方便入味，冷水下锅焯水捞出
2. 锅中少许油，鸡翅下锅煎至两面金黄（约 3 分钟/面）
3. 倒入可乐没过鸡翅，加生抽 2 勺、姜片 3~4 片
4. 大火烧开转中小火煮 15 分钟
5. 转大火收汁至浓稠，翻动防粘锅

**小贴士：** 用可口可乐比百事更好，甜度更合适。不要用零度可乐，没有糖无法收汁。

---

### 3. 番茄炒蛋

- **主料：** 西红柿 2 个、鸡蛋 3 个
- **配料：** 葱花
- **调料：** 盐、白糖少许
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人

**做法：**
1. 鸡蛋打散加少许盐搅匀，番茄切块（不要太小）
2. 锅中多放点油烧热，倒入蛋液，底部凝固后用铲子推成大块，八分熟盛出
3. 锅中留底油，下番茄块中火翻炒至出汁变软（约 2 分钟）
4. 加半勺糖提鲜（关键），加适量盐
5. 倒回鸡蛋翻炒均匀，出锅撒葱花

**小贴士：** 番茄顶部划十字用开水烫 30 秒可轻松去皮，口感更好。加糖是灵魂。

---

### 4. 酸辣土豆丝

- **主料：** 土豆 2 个
- **配料：** 干辣椒、花椒、蒜末
- **调料：** 醋、盐、鸡精
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人

**做法：**
1. 土豆去皮切细丝（越细越好），泡冷水 5 分钟洗去淀粉，沥干
2. 热锅冷油，小火爆香干辣椒段和花椒（花椒可夹出）
3. 大火下土豆丝，快速翻炒 1~2 分钟，保持脆感
4. 沿锅边淋醋 2 勺（醋遇热锅更香），加盐、鸡精
5. 翻炒均匀，断生即出锅（别炒过头）

**小贴士：** 切好的土豆丝一定要泡水洗掉淀粉，否则会粘连。全程大火快炒才脆。

---

### 5. 蒜蓉西兰花

- **主料：** 西兰花 1 颗
- **配料：** 大蒜 5~6 瓣
- **调料：** 盐、蚝油
- **难度：** ⭐ | **耗时：** 8 分钟 | **份量：** 2 人

**做法：**
1. 西兰花掰成小朵，淡盐水泡 10 分钟洗净
2. 烧开水加几滴油和少许盐，焯水 1 分钟捞出过凉水（保持翠绿）
3. 蒜切末，锅中油烧热爆香蒜末
4. 下西兰花大火翻炒 30 秒
5. 加盐、少许蚝油翻匀出锅

**小贴士：** 焯水时加油加盐能让西兰花更绿更入味。不要炒太久，保持脆感。

---

### 6. 红烧排骨

- **主料：** 排骨 500g
- **配料：** 葱、姜、八角
- **调料：** 冰糖/白糖、生抽、老抽、料酒
- **难度：** ⭐⭐ | **耗时：** 60 分钟 | **份量：** 2~3 人

**做法：**
1. 排骨冷水下锅，加料酒、姜片焯水 5 分钟，捞出洗净
2. 锅中少许油，放冰糖小火炒糖色至枣红色
3. 下排骨翻炒上色，加葱段、姜片、八角 2 颗
4. 加生抽 2 勺、老抽 1 勺、料酒 2 勺翻匀
5. 加开水没过排骨，大火烧开转小火炖 50 分钟
6. 大火收汁，汁浓挂在排骨上即可

**小贴士：** 排骨要充分焯水去血沫。炖的时候不要频繁开盖，保持小火慢炖。

---

### 7. 麻婆豆腐

- **主料：** 豆腐 1 块（北豆腐）、猪肉末 100g
- **配料：** 蒜苗/葱花
- **调料：** 豆瓣酱、花椒粉、生抽、淀粉
- **难度：** ⭐⭐ | **耗时：** 15 分钟 | **份量：** 2 人

**做法：**
1. 豆腐切 1.5cm 方块，烧盐水焯 2 分钟（定型不易碎），捞出
2. 锅中油烧热，下肉末炒散炒香至变色
3. 加 1 大勺豆瓣酱，小火炒出红油（约 1 分钟）
4. 加小半碗水，放入豆腐，轻推不要翻（防碎），中火煮 3 分钟
5. 加生抽调味，水淀粉勾芡，大火收至汤汁浓稠
6. 出锅撒花椒粉和葱花

**小贴士：** 豆腐焯水是关键步骤，不焯水容易碎。全程"推"不要"翻"。

---

### 8. 清炒空心菜

- **主料：** 空心菜 1 把
- **配料：** 大蒜 3~4 瓣、干辣椒 2 个
- **调料：** 盐、白糖少许
- **难度：** ⭐ | **耗时：** 5 分钟 | **份量：** 2 人

**做法：**
1. 空心菜摘洗干净，切段（梗和叶分开）
2. 蒜切末，干辣椒切段
3. 大火热锅热油，爆香蒜末和干辣椒
4. 先下菜梗炒 30 秒，再下菜叶大火快炒
5. 加盐、少许糖（提鲜），断生立即出锅

**小贴士：** 空心菜必须大火快炒，否则发黑。梗和叶分开下锅，熟度才一致。

---

### 9. 清蒸鲈鱼

- **主料：** 鲈鱼 1 条（约 500g）
- **配料：** 葱丝、姜丝、红椒丝
- **调料：** 蒸鱼豉油、料酒
- **难度：** ⭐⭐ | **耗时：** 20 分钟 | **份量：** 2~3 人

**做法：**
1. 鲈鱼去鳞去内脏洗净，鱼身两面各划 3 刀
2. 鱼身抹少许盐和料酒，塞入姜片，腌 10 分钟
3. 盘底铺葱段和姜片（架起鱼身），放上鲈鱼
4. 水烧开后大火蒸 8~10 分钟（鱼眼凸出即熟）
5. 倒掉盘中蒸出的汤汁（腥），铺上葱丝、姜丝、红椒丝
6. 淋上蒸鱼豉油 2 勺，浇上一勺滚烫热油（滋啦一声）

**小贴士：** 蒸鱼关键是火候——水开后再放鱼，大火蒸，时间到立刻取出。蒸过头肉会老。

---

### 10. 冬瓜丸子汤

- **主料：** 冬瓜 300g、猪肉馅 200g
- **配料：** 葱花、姜末、香菜
- **调料：** 盐、胡椒粉、料酒、淀粉
- **难度：** ⭐ | **耗时：** 25 分钟 | **份量：** 2~3 人

**做法：**
1. 冬瓜去皮去瓤切薄片
2. 肉馅加盐、料酒、姜末、少许淀粉，加 2 勺葱姜水，顺一个方向搅打上劲
3. 锅中加水烧至微沸（冒小泡不翻滚）
4. 用勺子挖肉馅，另一手辅助，下入圆丸子（水不要大开，防散）
5. 丸子浮起后下冬瓜片，煮至冬瓜透明（约 5 分钟）
6. 加盐、胡椒粉调味，撒葱花和香菜

**小贴士：** 肉馅一定要搅打上劲（有粘性），丸子才 Q 弹。水保持微沸下丸子，不要大火滚。

---

## 快手 10 分钟菜

### 11. 蒜蓉炒虾仁

- **主料：** 虾仁 200g
- **配料：** 大蒜 5 瓣、葱花
- **调料：** 盐、料酒、胡椒粉
- **难度：** ⭐ | **耗时：** 8 分钟 | **份量：** 2 人

**做法：**
1. 虾仁用料酒和少许盐腌 5 分钟
2. 蒜切末，锅中油爆香蒜末
3. 大火下虾仁翻炒至变色弯曲（约 2 分钟）
4. 加少许盐和胡椒粉，撒葱花出锅

---

### 12. 凉拌黄瓜

- **主料：** 黄瓜 2 根
- **配料：** 大蒜 3 瓣、干辣椒
- **调料：** 醋、生抽、盐、白糖、芝麻油、辣椒油
- **难度：** ⭐ | **耗时：** 5 分钟 | **份量：** 2 人

**做法：**
1. 黄瓜拍碎切段，加少许盐腌 2 分钟挤水
2. 蒜切末，调汁：生抽 2 勺 + 醋 1 勺 + 糖半勺 + 芝麻油 + 辣椒油
3. 浇在黄瓜上拌匀即可

---

### 13. 肥牛金针菇卷

- **主料：** 肥牛卷 200g、金针菇 1 把
- **配料：** 葱花
- **调料：** 生抽、蚝油、蒜蓉
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人

**做法：**
1. 金针菇去根洗净，用肥牛卷裹住金针菇
2. 卷好的肥牛金针菇摆盘
3. 调汁：生抽 2 勺 + 蚝油 1 勺 + 蒜蓉 + 少许水
4. 浇汁，蒸锅上汽蒸 8 分钟
5. 撒葱花，浇热油

---

### 14. 西红柿蛋花汤

- **主料：** 西红柿 1 个、鸡蛋 2 个
- **配料：** 葱花、香菜
- **调料：** 盐、白胡椒粉、芝麻油
- **难度：** ⭐ | **耗时：** 8 分钟 | **份量：** 2 人

**做法：**
1. 番茄切小块，鸡蛋打散
2. 锅中少许油炒软番茄至出汁
3. 加 2 碗水大火烧开
4. 转小火，用筷子引导缓慢倒入蛋液（蛋花更漂亮）
5. 加盐、白胡椒粉，滴几滴香油，撒葱花

---

## 清淡减脂菜

### 15. 白灼虾

- **主料：** 鲜虾 300g
- **配料：** 葱、姜、柠檬
- **调料：** 料酒
- **蘸料：** 生抽 + 姜末 + 蒜末 + 少许醋
- **难度：** ⭐ | **耗时：** 10 分钟 | **份量：** 2 人 | **热量：** ~200kcal

**做法：**
1. 虾去虾线洗净
2. 烧开水，加葱段、姜片、料酒、几片柠檬
3. 水开后下虾，煮至虾变红弯曲（约 2~3 分钟）
4. 捞出过冰水（口感更脆弹）
5. 调蘸料，蘸食即可

---

### 16. 水煮鸡胸肉沙拉

- **主料：** 鸡胸肉 1 块（200g）
- **配料：** 生菜、黄瓜、西红柿、玉米粒
- **调料：** 盐、黑胡椒、橄榄油、柠檬汁
- **难度：** ⭐ | **耗时：** 15 分钟 | **份量：** 1 人 | **热量：** ~300kcal

**做法：**
1. 鸡胸肉冷水下锅加姜片，水开后中火煮 10 分钟，关火焖 5 分钟
2. 捞出放凉撕成丝
3. 蔬菜洗净切块铺底
4. 调汁：橄榄油 + 柠檬汁 + 盐 + 黑胡椒
5. 鸡胸肉丝铺上，淋调汁

---

### 17. 清蒸鳕鱼

- **主料：** 鳕鱼 1 块（200g）
- **配料：** 葱丝、姜丝
- **调料：** 蒸鱼豉油、料酒
- **难度：** ⭐ | **耗时：** 15 分钟 | **份量：** 1 人 | **热量：** ~180kcal

**做法：**
1. 鳕鱼解冻擦干水分，抹料酒和少许盐腌 5 分钟
2. 盘底铺葱姜，放上鳕鱼
3. 水开后大火蒸 8 分钟
4. 倒掉蒸出的水，铺葱姜丝，淋蒸鱼豉油
5. 浇热油激出香味

---

## 川湘重口味菜

### 18. 辣子鸡

- **主料：** 鸡腿肉/鸡翅 400g
- **配料：** 干辣椒一大把、花椒、蒜、姜、葱
- **调料：** 料酒、生抽、盐、白糖、淀粉
- **难度：** ⭐⭐ | **耗时：** 25 分钟 | **份量：** 2~3 人

**做法：**
1. 鸡肉切小块，加盐、料酒、生抽、淀粉腌 15 分钟
2. 油温六成热（筷子入油起小泡），下鸡块炸至金黄捞出
3. 锅留底油，小火煸香干辣椒段和花椒（不要炒糊）
4. 下鸡块大火翻炒，加少许糖、盐
5. 撒葱花和白芝麻出锅

---

### 19. 水煮肉片

- **主料：** 里脊肉/猪肉 300g
- **配料：** 豆芽、生菜/油麦菜、蒜末、葱花
- **调料：** 豆瓣酱、干辣椒、花椒、料酒、生抽、淀粉
- **难度：** ⭐⭐ | **耗时：** 20 分钟 | **份量：** 2~3 人

**做法：**
1. 肉切薄片，加盐、料酒、蛋清、淀粉抓匀腌 10 分钟
2. 蔬菜焯水铺在碗底
3. 锅中油烧热，炒香豆瓣酱出红油，加蒜末、姜末
4. 加水（或高汤）烧开，下肉片拨散，煮至变色（约 1 分钟）
5. 连汤倒在蔬菜上
6. 面上铺蒜末、干辣椒段、花椒，浇一勺滚油（滋啦）

---

### 20. 剁椒鱼头

- **主料：** 鳙鱼头 1 个（胖头鱼）
- **配料：** 剁椒 3 大勺、姜蒜末、葱花
- **调料：** 料酒、生抽、盐
- **难度：** ⭐⭐ | **耗时：** 25 分钟 | **份量：** 2~3 人

**做法：**
1. 鱼头洗净对半剖开，抹盐和料酒腌 10 分钟
2. 盘底铺姜片葱段，放鱼头（切面朝上）
3. 鱼头上铺满剁椒，撒姜蒜末
4. 水开后大火蒸 12~15 分钟
5. 撒葱花，浇热油

---

## 菜品索引（按主料快查）

| 主料 | 可做菜品 |
|------|---------|
| 五花肉 | 红烧肉 |
| 鸡翅 | 可乐鸡翅 |
| 鸡蛋 + 西红柿 | 番茄炒蛋、西红柿蛋花汤 |
| 土豆 | 酸辣土豆丝 |
| 西兰花 | 蒜蓉西兰花 |
| 排骨 | 红烧排骨 |
| 豆腐 + 猪肉 | 麻婆豆腐 |
| 空心菜 | 清炒空心菜 |
| 鲈鱼 | 清蒸鲈鱼 |
| 冬瓜 + 猪肉 | 冬瓜丸子汤 |
| 虾/虾仁 | 蒜蓉炒虾仁、白灼虾 |
| 黄瓜 | 凉拌黄瓜 |
| 肥牛 + 金针菇 | 肥牛金针菇卷 |
| 鸡胸肉 | 水煮鸡胸肉沙拉 |
| 鳕鱼 | 清蒸鳕鱼 |
| 鸡腿/鸡肉 | 辣子鸡 |
| 里脊肉/猪肉 | 水煮肉片 |
| 鳙鱼 | 剁椒鱼头 |

## 菜品风格标签

| 风格 | 菜品编号 |
|------|---------|
| 家常 | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 |
| 快手10分钟 | 3, 4, 5, 8, 11, 12, 13, 14 |
| 清淡减脂 | 5, 14, 15, 16, 17 |
| 川湘重口 | 4, 7, 18, 19, 20 |

FILE:references/ingredients.md
# 食材数据库

所有支持的食材分类和列表。匹配用户输入时支持别名和模糊匹配。

## 肉类（20 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| M01 | 猪肉 | 瘦肉、前腿肉 | 炒、炖、蒸 | 通用肉类 |
| M02 | 五花肉 | 三层肉 | 红烧、煎、烤 | 肥瘦相间，红烧首选 |
| M03 | 排骨 | 肋排、小排 | 红烧、炖、蒸、糖醋 | 需焯水去腥 |
| M04 | 猪蹄 | 猪脚、猪手 | 红烧、炖、卤 | 富含胶原蛋白，炖煮时间长 |
| M05 | 里脊肉 | 猪里脊、小里脊 | 炒、炸、滑溜 | 嫩，适合快炒 |
| M06 | 猪肝 | — | 炒、卤、煮汤 | 需充分清洗，补铁 |
| M07 | 猪大肠 | 肥肠 | 卤、炒、干锅 | 需反复清洗去异味 |
| M08 | 牛肉 | — | 炒、炖、卤 | 纤维粗，需切逆纹 |
| M09 | 牛腩 | — | 炖、红烧、咖喱 | 适合慢炖，越炖越烂 |
| M10 | 牛腱子 | 牛腱 | 卤、炖 | 口感筋道，适合卤制 |
| M11 | 肥牛 | 肥牛卷、肥牛片 | 涮、炒、煮 | 薄片，快熟 |
| M12 | 羊肉 | — | 炖、涮、烤、炒 | 配萝卜去膻味 |
| M13 | 羊排 | — | 烤、炖、红焖 | 带骨更香 |
| M14 | 鸡肉 | 整鸡、鸡块 | 炖、蒸、炒、煮 | 万能蛋白质 |
| M15 | 鸡腿 | 琵琶腿、大鸡腿 | 红烧、烤、卤、炸 | 肉质嫩多汁 |
| M16 | 鸡翅 | 鸡翅中、翅中 | 可乐鸡翅、烤、炸、卤 | 需划刀方便入味 |
| M17 | 鸡爪 | 凤爪 | 卤、炖、泡椒 | 富含胶原蛋白 |
| M18 | 鸡胸肉 | 鸡胸 | 煎、炒、水煮 | 高蛋白低脂，减脂首选 |
| M19 | 鸭肉 | 整鸭、鸭块 | 炖、卤、烤 | 配啤酒或老鸭汤 |
| M20 | 鸭翅 | — | 卤、烤 | 适合卤制入味 |

## 水产海鲜（20 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| S01 | 草鱼 | — | 水煮、红烧、清蒸 | 刺多但肉厚 |
| S02 | 鲫鱼 | — | 煲汤、红烧 | 煲汤奶白色，鲜美 |
| S03 | 鲈鱼 | 海鲈鱼 | 清蒸、红烧 | 刺少肉嫩，清蒸首选 |
| S04 | 黑鱼 | 乌鱼、生鱼 | 酸菜鱼、煲汤 | 肉质紧实 |
| S05 | 黄骨鱼 | 黄辣丁、黄颡鱼 | 煲汤、红烧 | 肉嫩无小刺 |
| S06 | 鲢鱼 | 白鲢 | 水煮、炖 | 经济实惠 |
| S07 | 鳙鱼 | 胖头鱼、花鲢 | 剁椒鱼头、煲汤 | 鱼头大，胶质丰富 |
| S08 | 虾 | 基围虾、大虾、明虾 | 白灼、炒、蒸 | 蛋白质高，快熟 |
| S09 | 小龙虾 | 龙虾 | 蒜蓉、麻辣、十三香 | 需充分刷洗 |
| S10 | 螃蟹 | 大闸蟹、梭子蟹 | 清蒸、炒年糕 | 秋天最肥美 |
| S11 | 花甲 | 蛤蜊、蚬子 | 炒、煮汤、蒸 | 需提前吐沙 |
| S12 | 扇贝 | — | 蒜蓉粉丝蒸 | 蒜蓉蒸最经典 |
| S13 | 生蚝 | 牡蛎、海蛎子 | 蒜蓉烤、煎蛋 | 锌含量高 |
| S14 | 鱿鱼 | — | 炒、烤、干锅 | 需打花刀 |
| S15 | 墨鱼 | 乌贼 | 炒、炖汤 | 可取墨囊 |
| S16 | 八爪鱼 | 章鱼、小章鱼 | 炒、烤、凉拌 | 焯水后口感好 |
| S17 | 带鱼 | — | 煎、红烧、糖醋 | 需去内脏和黑膜 |
| S18 | 黄花鱼 | 黄鱼 | 红烧、煎、炖 | 肉嫩味鲜 |
| S19 | 鳕鱼 | — | 煎、蒸、烤 | 肉质细嫩，无刺 |
| S20 | 三文鱼 | 鲑鱼 | 刺身、煎、烤 | 生食需确保新鲜度 |

## 蛋类 & 豆制品（10 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| E01 | 鸡蛋 | 蛋 | 炒、煎、蒸、煮 | 万能食材 |
| E02 | 鸭蛋 | — | 腌制、煎 | 咸鸭蛋更常见 |
| E03 | 鹅蛋 | — | 煎、蒸 | 个头大，蛋香浓 |
| E04 | 鹌鹑蛋 | — | 卤、煮、炖 | 小巧玲珑 |
| E05 | 豆腐 | 老豆腐、北豆腐 | 红烧、煎、炖 | 质地较硬，适合煎炒 |
| E06 | 嫩豆腐 | 内酯豆腐、南豆腐 | 蒸、煮汤、凉拌 | 质地软嫩 |
| E07 | 冻豆腐 | — | 炖、火锅、煮 | 口感像海绵，吸汁 |
| E08 | 豆干 | 豆腐干、香干 | 炒、卤、凉拌 | 口感紧实 |
| E09 | 千张 | 豆皮、百叶 | 凉拌、炒、卷 | 薄如纸张 |
| E10 | 腐竹 | — | 炖、凉拌、炒 | 需提前泡发 |

## 蔬菜（31 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| V01 | 白菜 | 大白菜 | 炒、炖、煮、腌 | 百搭蔬菜 |
| V02 | 娃娃菜 | 小白菜 | 蒜蓉、煮汤、炒 | 比大白菜更嫩甜 |
| V03 | 菠菜 | — | 炒、煮汤、凉拌 | 焯水去草酸 |
| V04 | 生菜 | — | 生吃、蒜蓉、涮 | 口感脆嫩 |
| V05 | 油麦菜 | — | 蒜蓉、炒 | 类似生菜但更长 |
| V06 | 空心菜 | 通菜、蕹菜 | 清炒、蒜蓉 | 大火快炒防变黑 |
| V07 | 韭菜 | — | 炒蛋、饺子馅 | 香味浓，快熟 |
| V08 | 芹菜 | 西芹 | 炒、凉拌 | 可去筋口感更好 |
| V09 | 香菜 | 芫荽 | 配菜、凉拌 | 提味点缀用 |
| V10 | 茼蒿 | — | 清炒、涮火锅 | 火锅必备蔬菜 |
| V11 | 西兰花 | 绿花菜 | 蒜蓉、白灼、炒 | 焯水后更翠绿 |
| V12 | 菜花 | 花菜、白花菜 | 干锅、炒、烤 | 掰小朵更入味 |
| V13 | 黄瓜 | 青瓜 | 凉拌、炒 | 拍碎比切更入味 |
| V14 | 冬瓜 | — | 炖汤、红烧 | 利尿消肿 |
| V15 | 南瓜 | — | 蒸、煮粥、炒 | 甜糯口感 |
| V16 | 丝瓜 | — | 炒蛋、煮汤 | 去皮后快炒 |
| V17 | 苦瓜 | 凉瓜 | 炒蛋、凉拌 | 焯水可减苦味 |
| V18 | 茄子 | — | 红烧、蒸、烤 | 吸油大户，可先蒸 |
| V19 | 西红柿 | 番茄 | 炒蛋、煮汤、酱 | 万能配菜 |
| V20 | 土豆 | 马铃薯 | 炒丝、炖、焖 | 切丝泡水防变色 |
| V21 | 山药 | 淮山 | 炒、炖、蒸 | 去皮戴手套防痒 |
| V22 | 红薯 | 地瓜、番薯 | 蒸、烤、煮粥 | 软糯香甜 |
| V23 | 胡萝卜 | 红萝卜 | 炒、炖、煮 | 过油更易吸收 |
| V24 | 白萝卜 | — | 炖、煮汤、凉拌 | 冬吃萝卜，清甜 |
| V25 | 洋葱 | — | 炒、配菜、凉拌 | 切丝泡水减辣 |
| V26 | 大蒜 | 蒜头 | 调味、蒜蓉 | 百搭调味 |
| V27 | 生姜 | 姜 | 调味、去腥 | 肉类必备 |
| V28 | 青椒 | 柿子椒 | 炒肉、配菜 | 微辣，口感脆 |
| V29 | 红椒 | 彩椒 | 炒、配色 | 甜脆，提色 |
| V30 | 莲藕 | 藕 | 炒、炖、凉拌 | 脆藕炒，粉藕炖 |
| V31 | 金针菇 | — | 烤、涮、炒 | 需去根部 |

## 干货 & 菌菇（10 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| D01 | 香菇 | 冬菇 | 炒、炖、蒸 | 干香菇需泡发，水可做汤底 |
| D02 | 木耳 | 黑木耳 | 炒、凉拌 | 干木耳泡发后体积增大数倍 |
| D03 | 银耳 | 白木耳 | 甜汤、炖 | 需泡发撕小朵 |
| D04 | 海带 | 昆布 | 炖、凉拌、煮汤 | 需提前泡软 |
| D05 | 紫菜 | — | 煮汤、包饭 | 即食型可直接用 |
| D06 | 腐竹 | — | 炖、凉拌、炒 | 需提前泡发 2~4 小时 |
| D07 | 粉丝 | 龙口粉丝 | 炖、煮、炒 | 热水泡软即可 |
| D08 | 粉条 | 红薯粉条 | 炖、炒 | 口感比粉丝更筋道 |
| D09 | 黄花菜 | 金针菜 | 炒、炖、煮汤 | 干的需泡发，鲜的需焯水 |
| D10 | 茶树菇 | — | 炒、炖 | 干的需泡发，菌香浓 |

## 主食杂粮（10 种）

| 编号 | 食材 | 常见别名 | 适合烹饪方式 | 备注 |
|------|------|----------|-------------|------|
| G01 | 大米 | 白米 | 蒸饭、煮粥 | 主食首选 |
| G02 | 小米 | 黄小米 | 煮粥 | 养胃 |
| G03 | 糯米 | 江米 | 粽子、糯米饭、汤圆 | 黏性大 |
| G04 | 玉米 | — | 煮、蒸、炒 | 甜玉米/糯玉米 |
| G05 | 面条 | 挂面、手擀面 | 煮、炒、拌 | 快手主食 |
| G06 | 馒头 | — | 蒸、煎 | 配菜搭档 |
| G07 | 面粉 | 中筋粉 | 包饺子、煎饼、面疙瘩 | 万能主食原料 |
| G08 | 绿豆 | — | 煮汤、煮粥 | 夏天消暑 |
| G09 | 红豆 | 赤小豆 | 煮粥、煮汤 | 需提前泡 |
| G10 | 花生 | — | 炒、煮、炖 | 配菜或零嘴 |

## 默认视为已有的调味料

以下调料在推荐菜谱时默认用户家中已有，不需要额外确认：

- **基础调味：** 盐、白糖、鸡精/味精
- **酱油类：** 生抽、老抽、蚝油
- **酒醋类：** 料酒、米醋/白醋、陈醋
- **油脂类：** 食用油、芝麻油/香油
- **辛香料：** 干辣椒、花椒、八角、桂皮、香叶
- **酱料类：** 豆瓣酱、甜面酱、番茄酱
- **粉类：** 淀粉/生粉、胡椒粉、五香粉、十三香
- **其他：** 葱、蒜、姜（也列在蔬菜中，但作为调味时默认有）

FILE:evals/evals.json
{
  "skill_name": "daily-menu",
  "evals": [
    {
      "id": 1,
      "prompt": "我冰箱里有鸡翅和土豆，今晚做什么菜好？",
      "expected_output": "推荐可乐鸡翅和酸辣土豆丝，给出详细做法和备菜清单",
      "expectations": [
        "推荐的菜品使用了鸡翅和土豆",
        "给出了具体的烹饪步骤和时间",
        "包含备菜清单",
        "菜品荤素搭配"
      ]
    },
    {
      "id": 2,
      "prompt": "家里有五花肉和冬瓜，3个人吃饭，帮我安排一下",
      "expected_output": "推荐红烧肉和冬瓜丸子汤等菜品，考虑3人份量",
      "expectations": [
        "推荐的菜用到了五花肉和冬瓜",
        "考虑了3人的份量",
        "给出了烹饪时间线建议"
      ]
    },
    {
      "id": 3,
      "prompt": "我在减肥，有鸡胸肉和西兰花，推荐减脂餐",
      "expected_output": "推荐清淡减脂菜品如水煮鸡胸肉沙拉和蒜蓉西兰花",
      "expectations": [
        "推荐的菜符合减脂风格",
        "给出了热量估算",
        "烹饪方式清淡（蒸、煮、白灼等）"
      ]
    },
    {
      "id": 4,
      "prompt": "只有10分钟，虾和黄瓜能做啥？",
      "expected_output": "推荐蒜蓉炒虾仁和凉拌黄瓜等快手菜",
      "expectations": [
        "推荐的菜品都在10分钟以内",
        "用到了虾和黄瓜",
        "做法简单快捷"
      ]
    },
    {
      "id": 5,
      "prompt": "今天想吃辣的，家里有里脊肉和豆腐",
      "expected_output": "推荐川湘重口味菜品如水煮肉片和麻婆豆腐",
      "expectations": [
        "推荐的菜品是重口味/川湘风格",
        "用到了里脊肉和豆腐",
        "包含辣椒/花椒等调料"
      ]
    }
  ]
}

---
name: self-improvement
description: "Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Claude ('No, that's wrong...', 'Actually...'), (3) User requests a capability that doesn't exist, (4) An external API or tool fails, (5) Claude realizes its knowledge is outdated or incorrect, (6) A better approach is discovered for a recurring task. Also review learnings before major tasks."
metadata:
---

# Self-Improvement Skill

Log learnings and errors to markdown files for continuous improvement. Coding agents can later process these into fixes, and important learnings get promoted to project memory.

## Quick Reference

| Situation | Action |
|-----------|--------|
| Command/operation fails | Log to `.learnings/ERRORS.md` |
| User corrects you | Log to `.learnings/LEARNINGS.md` with category `correction` |
| User wants missing feature | Log to `.learnings/FEATURE_REQUESTS.md` |
| API/external tool fails | Log to `.learnings/ERRORS.md` with integration details |
| Knowledge was outdated | Log to `.learnings/LEARNINGS.md` with category `knowledge_gap` |
| Found better approach | Log to `.learnings/LEARNINGS.md` with category `best_practice` |
| Simplify/Harden recurring patterns | Log/update `.learnings/LEARNINGS.md` with `Source: simplify-and-harden` and a stable `Pattern-Key` |
| Similar to existing entry | Link with `**See Also**`, consider priority bump |
| Broadly applicable learning | Promote to `CLAUDE.md`, `AGENTS.md`, and/or `.github/copilot-instructions.md` |
| Workflow improvements | Promote to `AGENTS.md` (OpenClaw workspace) |
| Tool gotchas | Promote to `TOOLS.md` (OpenClaw workspace) |
| Behavioral patterns | Promote to `SOUL.md` (OpenClaw workspace) |

## OpenClaw Setup (Recommended)

OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading.

### Installation

**Via ClawdHub (recommended):**
```bash
clawdhub install self-improving-agent
```

**Manual:**
```bash
git clone https://github.com/peterskoett/self-improving-agent.git ~/.openclaw/skills/self-improving-agent
```

Remade for openclaw from original repo : https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement

### Workspace Structure

OpenClaw injects these files into every session:

```
~/.openclaw/workspace/
├── AGENTS.md          # Multi-agent workflows, delegation patterns
├── SOUL.md            # Behavioral guidelines, personality, principles
├── TOOLS.md           # Tool capabilities, integration gotchas
├── MEMORY.md          # Long-term memory (main session only)
├── memory/            # Daily memory files
│   └── YYYY-MM-DD.md
└── .learnings/        # This skill's log files
    ├── LEARNINGS.md
    ├── ERRORS.md
    └── FEATURE_REQUESTS.md
```

### Create Learning Files

```bash
mkdir -p ~/.openclaw/workspace/.learnings
```

Then create the log files (or copy from `assets/`):
- `LEARNINGS.md` — corrections, knowledge gaps, best practices
- `ERRORS.md` — command failures, exceptions
- `FEATURE_REQUESTS.md` — user-requested capabilities

### Promotion Targets

When learnings prove broadly applicable, promote them to workspace files:

| Learning Type | Promote To | Example |
|---------------|------------|---------|
| Behavioral patterns | `SOUL.md` | "Be concise, avoid disclaimers" |
| Workflow improvements | `AGENTS.md` | "Spawn sub-agents for long tasks" |
| Tool gotchas | `TOOLS.md` | "Git push needs auth configured first" |

### Inter-Session Communication

OpenClaw provides tools to share learnings across sessions:

- **sessions_list** — View active/recent sessions
- **sessions_history** — Read another session's transcript  
- **sessions_send** — Send a learning to another session
- **sessions_spawn** — Spawn a sub-agent for background work

### Optional: Enable Hook

For automatic reminders at session start:

```bash
# Copy hook to OpenClaw hooks directory
cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement

# Enable it
openclaw hooks enable self-improvement
```

See `references/openclaw-integration.md` for complete details.

---

## Generic Setup (Other Agents)

For Claude Code, Codex, Copilot, or other agents, create `.learnings/` in your project:

```bash
mkdir -p .learnings
```

Copy templates from `assets/` or create files with headers.

### Add reference to agent files AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md to remind yourself to log learnings. (this is an alternative to hook-based reminders)

#### Self-Improvement Workflow

When errors or corrections occur:
1. Log to `.learnings/ERRORS.md`, `LEARNINGS.md`, or `FEATURE_REQUESTS.md`
2. Review and promote broadly applicable learnings to:
   - `CLAUDE.md` - project facts and conventions
   - `AGENTS.md` - workflows and automation
   - `.github/copilot-instructions.md` - Copilot context

## Logging Format

### Learning Entry

Append to `.learnings/LEARNINGS.md`:

```markdown
## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
One-line description of what was learned

### Details
Full context: what happened, what was wrong, what's correct

### Suggested Action
Specific fix or improvement to make

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file.ext
- Tags: tag1, tag2
- See Also: LRN-20250110-001 (if related to existing entry)
- Pattern-Key: simplify.dead_code | harden.input_validation (optional, for recurring-pattern tracking)
- Recurrence-Count: 1 (optional)
- First-Seen: 2025-01-15 (optional)
- Last-Seen: 2025-01-15 (optional)

---
```

### Error Entry

Append to `.learnings/ERRORS.md`:

```markdown
## [ERR-YYYYMMDD-XXX] skill_or_command_name

**Logged**: ISO-8601 timestamp
**Priority**: high
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
Brief description of what failed

### Error
```
Actual error message or output
```

### Context
- Command/operation attempted
- Input or parameters used
- Environment details if relevant

### Suggested Fix
If identifiable, what might resolve this

### Metadata
- Reproducible: yes | no | unknown
- Related Files: path/to/file.ext
- See Also: ERR-20250110-001 (if recurring)

---
```

### Feature Request Entry

Append to `.learnings/FEATURE_REQUESTS.md`:

```markdown
## [FEAT-YYYYMMDD-XXX] capability_name

**Logged**: ISO-8601 timestamp
**Priority**: medium
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Requested Capability
What the user wanted to do

### User Context
Why they needed it, what problem they're solving

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
How this could be built, what it might extend

### Metadata
- Frequency: first_time | recurring
- Related Features: existing_feature_name

---
```

## ID Generation

Format: `TYPE-YYYYMMDD-XXX`
- TYPE: `LRN` (learning), `ERR` (error), `FEAT` (feature)
- YYYYMMDD: Current date
- XXX: Sequential number or random 3 chars (e.g., `001`, `A7B`)

Examples: `LRN-20250115-001`, `ERR-20250115-A3F`, `FEAT-20250115-002`

## Resolving Entries

When an issue is fixed, update the entry:

1. Change `**Status**: pending` → `**Status**: resolved`
2. Add resolution block after Metadata:

```markdown
### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Commit/PR**: abc123 or #42
- **Notes**: Brief description of what was done
```

Other status values:
- `in_progress` - Actively being worked on
- `wont_fix` - Decided not to address (add reason in Resolution notes)
- `promoted` - Elevated to CLAUDE.md, AGENTS.md, or .github/copilot-instructions.md

## Promoting to Project Memory

When a learning is broadly applicable (not a one-off fix), promote it to permanent project memory.

### When to Promote

- Learning applies across multiple files/features
- Knowledge any contributor (human or AI) should know
- Prevents recurring mistakes
- Documents project-specific conventions

### Promotion Targets

| Target | What Belongs There |
|--------|-------------------|
| `CLAUDE.md` | Project facts, conventions, gotchas for all Claude interactions |
| `AGENTS.md` | Agent-specific workflows, tool usage patterns, automation rules |
| `.github/copilot-instructions.md` | Project context and conventions for GitHub Copilot |
| `SOUL.md` | Behavioral guidelines, communication style, principles (OpenClaw workspace) |
| `TOOLS.md` | Tool capabilities, usage patterns, integration gotchas (OpenClaw workspace) |

### How to Promote

1. **Distill** the learning into a concise rule or fact
2. **Add** to appropriate section in target file (create file if needed)
3. **Update** original entry:
   - Change `**Status**: pending` → `**Status**: promoted`
   - Add `**Promoted**: CLAUDE.md`, `AGENTS.md`, or `.github/copilot-instructions.md`

### Promotion Examples

**Learning** (verbose):
> Project uses pnpm workspaces. Attempted `npm install` but failed. 
> Lock file is `pnpm-lock.yaml`. Must use `pnpm install`.

**In CLAUDE.md** (concise):
```markdown
## Build & Dependencies
- Package manager: pnpm (not npm) - use `pnpm install`
```

**Learning** (verbose):
> When modifying API endpoints, must regenerate TypeScript client.
> Forgetting this causes type mismatches at runtime.

**In AGENTS.md** (actionable):
```markdown
## After API Changes
1. Regenerate client: `pnpm run generate:api`
2. Check for type errors: `pnpm tsc --noEmit`
```

## Recurring Pattern Detection

If logging something similar to an existing entry:

1. **Search first**: `grep -r "keyword" .learnings/`
2. **Link entries**: Add `**See Also**: ERR-20250110-001` in Metadata
3. **Bump priority** if issue keeps recurring
4. **Consider systemic fix**: Recurring issues often indicate:
   - Missing documentation (→ promote to CLAUDE.md or .github/copilot-instructions.md)
   - Missing automation (→ add to AGENTS.md)
   - Architectural problem (→ create tech debt ticket)

## Simplify & Harden Feed

Use this workflow to ingest recurring patterns from the `simplify-and-harden`
skill and turn them into durable prompt guidance.

### Ingestion Workflow

1. Read `simplify_and_harden.learning_loop.candidates` from the task summary.
2. For each candidate, use `pattern_key` as the stable dedupe key.
3. Search `.learnings/LEARNINGS.md` for an existing entry with that key:
   - `grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md`
4. If found:
   - Increment `Recurrence-Count`
   - Update `Last-Seen`
   - Add `See Also` links to related entries/tasks
5. If not found:
   - Create a new `LRN-...` entry
   - Set `Source: simplify-and-harden`
   - Set `Pattern-Key`, `Recurrence-Count: 1`, and `First-Seen`/`Last-Seen`

### Promotion Rule (System Prompt Feedback)

Promote recurring patterns into agent context/system prompt files when all are true:

- `Recurrence-Count >= 3`
- Seen across at least 2 distinct tasks
- Occurred within a 30-day window

Promotion targets:
- `CLAUDE.md`
- `AGENTS.md`
- `.github/copilot-instructions.md`
- `SOUL.md` / `TOOLS.md` for OpenClaw workspace-level guidance when applicable

Write promoted rules as short prevention rules (what to do before/while coding),
not long incident write-ups.

## Periodic Review

Review `.learnings/` at natural breakpoints:

### When to Review
- Before starting a new major task
- After completing a feature
- When working in an area with past learnings
- Weekly during active development

### Quick Status Check
```bash
# Count pending items
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

# List pending high-priority items
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["

# Find learnings for a specific area
grep -l "Area\*\*: backend" .learnings/*.md
```

### Review Actions
- Resolve fixed items
- Promote applicable learnings
- Link related entries
- Escalate recurring issues

## Detection Triggers

Automatically log when you notice:

**Corrections** (→ learning with `correction` category):
- "No, that's not right..."
- "Actually, it should be..."
- "You're wrong about..."
- "That's outdated..."

**Feature Requests** (→ feature request):
- "Can you also..."
- "I wish you could..."
- "Is there a way to..."
- "Why can't you..."

**Knowledge Gaps** (→ learning with `knowledge_gap` category):
- User provides information you didn't know
- Documentation you referenced is outdated
- API behavior differs from your understanding

**Errors** (→ error entry):
- Command returns non-zero exit code
- Exception or stack trace
- Unexpected output or behavior
- Timeout or connection failure

## Priority Guidelines

| Priority | When to Use |
|----------|-------------|
| `critical` | Blocks core functionality, data loss risk, security issue |
| `high` | Significant impact, affects common workflows, recurring issue |
| `medium` | Moderate impact, workaround exists |
| `low` | Minor inconvenience, edge case, nice-to-have |

## Area Tags

Use to filter learnings by codebase region:

| Area | Scope |
|------|-------|
| `frontend` | UI, components, client-side code |
| `backend` | API, services, server-side code |
| `infra` | CI/CD, deployment, Docker, cloud |
| `tests` | Test files, testing utilities, coverage |
| `docs` | Documentation, comments, READMEs |
| `config` | Configuration files, environment, settings |

## Best Practices

1. **Log immediately** - context is freshest right after the issue
2. **Be specific** - future agents need to understand quickly
3. **Include reproduction steps** - especially for errors
4. **Link related files** - makes fixes easier
5. **Suggest concrete fixes** - not just "investigate"
6. **Use consistent categories** - enables filtering
7. **Promote aggressively** - if in doubt, add to CLAUDE.md or .github/copilot-instructions.md
8. **Review regularly** - stale learnings lose value

## Gitignore Options

**Keep learnings local** (per-developer):
```gitignore
.learnings/
```

**Track learnings in repo** (team-wide):
Don't add to .gitignore - learnings become shared knowledge.

**Hybrid** (track templates, ignore entries):
```gitignore
.learnings/*.md
!.learnings/.gitkeep
```

## Hook Integration

Enable automatic reminders through agent hooks. This is **opt-in** - you must explicitly configure hooks.

### Quick Setup (Claude Code / Codex)

Create `.claude/settings.json` in your project:

```json
{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }]
  }
}
```

This injects a learning evaluation reminder after each prompt (~50-100 tokens overhead).

### Full Setup (With Error Detection)

```json
{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/error-detector.sh"
      }]
    }]
  }
}
```

### Available Hook Scripts

| Script | Hook Type | Purpose |
|--------|-----------|---------|
| `scripts/activator.sh` | UserPromptSubmit | Reminds to evaluate learnings after tasks |
| `scripts/error-detector.sh` | PostToolUse (Bash) | Triggers on command errors |

See `references/hooks-setup.md` for detailed configuration and troubleshooting.

## Automatic Skill Extraction

When a learning is valuable enough to become a reusable skill, extract it using the provided helper.

### Skill Extraction Criteria

A learning qualifies for skill extraction when ANY of these apply:

| Criterion | Description |
|-----------|-------------|
| **Recurring** | Has `See Also` links to 2+ similar issues |
| **Verified** | Status is `resolved` with working fix |
| **Non-obvious** | Required actual debugging/investigation to discover |
| **Broadly applicable** | Not project-specific; useful across codebases |
| **User-flagged** | User says "save this as a skill" or similar |

### Extraction Workflow

1. **Identify candidate**: Learning meets extraction criteria
2. **Run helper** (or create manually):
   ```bash
   ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improvement/scripts/extract-skill.sh skill-name
   ```
3. **Customize SKILL.md**: Fill in template with learning content
4. **Update learning**: Set status to `promoted_to_skill`, add `Skill-Path`
5. **Verify**: Read skill in fresh session to ensure it's self-contained

### Manual Extraction

If you prefer manual creation:

1. Create `skills/<skill-name>/SKILL.md`
2. Use template from `assets/SKILL-TEMPLATE.md`
3. Follow [Agent Skills spec](https://agentskills.io/specification):
   - YAML frontmatter with `name` and `description`
   - Name must match folder name
   - No README.md inside skill folder

### Extraction Detection Triggers

Watch for these signals that a learning should become a skill:

**In conversation:**
- "Save this as a skill"
- "I keep running into this"
- "This would be useful for other projects"
- "Remember this pattern"

**In learning entries:**
- Multiple `See Also` links (recurring issue)
- High priority + resolved status
- Category: `best_practice` with broad applicability
- User feedback praising the solution

### Skill Quality Gates

Before extraction, verify:

- [ ] Solution is tested and working
- [ ] Description is clear without original context
- [ ] Code examples are self-contained
- [ ] No project-specific hardcoded values
- [ ] Follows skill naming conventions (lowercase, hyphens)

## Multi-Agent Support

This skill works across different AI coding agents with agent-specific activation.

### Claude Code

**Activation**: Hooks (UserPromptSubmit, PostToolUse)
**Setup**: `.claude/settings.json` with hook configuration
**Detection**: Automatic via hook scripts

### Codex CLI

**Activation**: Hooks (same pattern as Claude Code)
**Setup**: `.codex/settings.json` with hook configuration
**Detection**: Automatic via hook scripts

### GitHub Copilot

**Activation**: Manual (no hook support)
**Setup**: Add to `.github/copilot-instructions.md`:

```markdown
## Self-Improvement

After solving non-obvious issues, consider logging to `.learnings/`:
1. Use format from self-improvement skill
2. Link related entries with See Also
3. Promote high-value learnings to skills

Ask in chat: "Should I log this as a learning?"
```

**Detection**: Manual review at session end

### OpenClaw

**Activation**: Workspace injection + inter-agent messaging
**Setup**: See "OpenClaw Setup" section above
**Detection**: Via session tools and workspace files

### Agent-Agnostic Guidance

Regardless of agent, apply self-improvement when you:

1. **Discover something non-obvious** - solution wasn't immediate
2. **Correct yourself** - initial approach was wrong
3. **Learn project conventions** - discovered undocumented patterns
4. **Hit unexpected errors** - especially if diagnosis was difficult
5. **Find better approaches** - improved on your original solution

### Copilot Chat Integration

For Copilot users, add this to your prompts when relevant:

> After completing this task, evaluate if any learnings should be logged to `.learnings/` using the self-improvement skill format.

Or use quick prompts:
- "Log this to learnings"
- "Create a skill from this solution"
- "Check .learnings/ for related issues"

FILE:_meta.json
{
  "ownerId": "kn70cjr952qdec1nx70zs6wefn7ynq2t",
  "slug": "self-improving-agent",
  "version": "3.0.5",
  "publishedAt": 1773760428300
}
FILE:.learnings/FEATURE_REQUESTS.md
# Feature Requests

Capabilities requested by user that don't currently exist.

---

FILE:.learnings/ERRORS.md
# Errors Log

Command failures, exceptions, and unexpected behaviors.

---

FILE:.learnings/LEARNINGS.md
# Learnings Log

Captured learnings, corrections, and discoveries. Review before major tasks.

---

FILE:assets/SKILL-TEMPLATE.md
# Skill Template

Template for creating skills extracted from learnings. Copy and customize.

---

## SKILL.md Template

```markdown
---
name: skill-name-here
description: "Concise description of when and why to use this skill. Include trigger conditions."
---

# Skill Name

Brief introduction explaining the problem this skill solves and its origin.

## Quick Reference

| Situation | Action |
|-----------|--------|
| [Trigger 1] | [Action 1] |
| [Trigger 2] | [Action 2] |

## Background

Why this knowledge matters. What problems it prevents. Context from the original learning.

## Solution

### Step-by-Step

1. First step with code or command
2. Second step
3. Verification step

### Code Example

\`\`\`language
// Example code demonstrating the solution
\`\`\`

## Common Variations

- **Variation A**: Description and how to handle
- **Variation B**: Description and how to handle

## Gotchas

- Warning or common mistake #1
- Warning or common mistake #2

## Related

- Link to related documentation
- Link to related skill

## Source

Extracted from learning entry.
- **Learning ID**: LRN-YYYYMMDD-XXX
- **Original Category**: correction | insight | knowledge_gap | best_practice
- **Extraction Date**: YYYY-MM-DD
```

---

## Minimal Template

For simple skills that don't need all sections:

```markdown
---
name: skill-name-here
description: "What this skill does and when to use it."
---

# Skill Name

[Problem statement in one sentence]

## Solution

[Direct solution with code/commands]

## Source

- Learning ID: LRN-YYYYMMDD-XXX
```

---

## Template with Scripts

For skills that include executable helpers:

```markdown
---
name: skill-name-here
description: "What this skill does and when to use it."
---

# Skill Name

[Introduction]

## Quick Reference

| Command | Purpose |
|---------|---------|
| `./scripts/helper.sh` | [What it does] |
| `./scripts/validate.sh` | [What it does] |

## Usage

### Automated (Recommended)

\`\`\`bash
./skills/skill-name/scripts/helper.sh [args]
\`\`\`

### Manual Steps

1. Step one
2. Step two

## Scripts

| Script | Description |
|--------|-------------|
| `scripts/helper.sh` | Main utility |
| `scripts/validate.sh` | Validation checker |

## Source

- Learning ID: LRN-YYYYMMDD-XXX
```

---

## Naming Conventions

- **Skill name**: lowercase, hyphens for spaces
  - Good: `docker-m1-fixes`, `api-timeout-patterns`
  - Bad: `Docker_M1_Fixes`, `APITimeoutPatterns`

- **Description**: Start with action verb, mention trigger
  - Good: "Handles Docker build failures on Apple Silicon. Use when builds fail with platform mismatch."
  - Bad: "Docker stuff"

- **Files**:
  - `SKILL.md` - Required, main documentation
  - `scripts/` - Optional, executable code
  - `references/` - Optional, detailed docs
  - `assets/` - Optional, templates

---

## Extraction Checklist

Before creating a skill from a learning:

- [ ] Learning is verified (status: resolved)
- [ ] Solution is broadly applicable (not one-off)
- [ ] Content is complete (has all needed context)
- [ ] Name follows conventions
- [ ] Description is concise but informative
- [ ] Quick Reference table is actionable
- [ ] Code examples are tested
- [ ] Source learning ID is recorded

After creating:

- [ ] Update original learning with `promoted_to_skill` status
- [ ] Add `Skill-Path: skills/skill-name` to learning metadata
- [ ] Test skill by reading it in a fresh session

FILE:assets/LEARNINGS.md
# Learnings

Corrections, insights, and knowledge gaps captured during development.

**Categories**: correction | insight | knowledge_gap | best_practice
**Areas**: frontend | backend | infra | tests | docs | config
**Statuses**: pending | in_progress | resolved | wont_fix | promoted | promoted_to_skill

## Status Definitions

| Status | Meaning |
|--------|---------|
| `pending` | Not yet addressed |
| `in_progress` | Actively being worked on |
| `resolved` | Issue fixed or knowledge integrated |
| `wont_fix` | Decided not to address (reason in Resolution) |
| `promoted` | Elevated to CLAUDE.md, AGENTS.md, or copilot-instructions.md |
| `promoted_to_skill` | Extracted as a reusable skill |

## Skill Extraction Fields

When a learning is promoted to a skill, add these fields:

```markdown
**Status**: promoted_to_skill
**Skill-Path**: skills/skill-name
```

Example:
```markdown
## [LRN-20250115-001] best_practice

**Logged**: 2025-01-15T10:00:00Z
**Priority**: high
**Status**: promoted_to_skill
**Skill-Path**: skills/docker-m1-fixes
**Area**: infra

### Summary
Docker build fails on Apple Silicon due to platform mismatch
...
```

---


FILE:scripts/activator.sh
#!/bin/bash
# Self-Improvement Activator Hook
# Triggers on UserPromptSubmit to remind Claude about learning capture
# Keep output minimal (~50-100 tokens) to minimize overhead

set -e

# Output reminder as system context
cat << 'EOF'
<self-improvement-reminder>
After completing this task, evaluate if extractable knowledge emerged:
- Non-obvious solution discovered through investigation?
- Workaround for unexpected behavior?
- Project-specific pattern learned?
- Error required debugging to resolve?

If yes: Log to .learnings/ using the self-improvement skill format.
If high-value (recurring, broadly applicable): Consider skill extraction.
</self-improvement-reminder>
EOF

FILE:scripts/extract-skill.sh
#!/bin/bash
# Skill Extraction Helper
# Creates a new skill from a learning entry
# Usage: ./extract-skill.sh <skill-name> [--dry-run]

set -e

# Configuration
SKILLS_DIR="./skills"

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

usage() {
    cat << EOF
Usage: $(basename "$0") <skill-name> [options]

Create a new skill from a learning entry.

Arguments:
  skill-name     Name of the skill (lowercase, hyphens for spaces)

Options:
  --dry-run      Show what would be created without creating files
  --output-dir   Relative output directory under current path (default: ./skills)
  -h, --help     Show this help message

Examples:
  $(basename "$0") docker-m1-fixes
  $(basename "$0") api-timeout-patterns --dry-run
  $(basename "$0") pnpm-setup --output-dir ./skills/custom

The skill will be created in: \$SKILLS_DIR/<skill-name>/
EOF
}

log_info() {
    echo -e "GREEN[INFO]NC $1"
}

log_warn() {
    echo -e "YELLOW[WARN]NC $1"
}

log_error() {
    echo -e "RED[ERROR]NC $1" >&2
}

# Parse arguments
SKILL_NAME=""
DRY_RUN=false

while [[ $# -gt 0 ]]; do
    case $1 in
        --dry-run)
            DRY_RUN=true
            shift
            ;;
        --output-dir)
            if [ -z "-" ] || [[ "-" == -* ]]; then
                log_error "--output-dir requires a relative path argument"
                usage
                exit 1
            fi
            SKILLS_DIR="$2"
            shift 2
            ;;
        -h|--help)
            usage
            exit 0
            ;;
        -*)
            log_error "Unknown option: $1"
            usage
            exit 1
            ;;
        *)
            if [ -z "$SKILL_NAME" ]; then
                SKILL_NAME="$1"
            else
                log_error "Unexpected argument: $1"
                usage
                exit 1
            fi
            shift
            ;;
    esac
done

# Validate skill name
if [ -z "$SKILL_NAME" ]; then
    log_error "Skill name is required"
    usage
    exit 1
fi

# Validate skill name format (lowercase, hyphens, no spaces)
if ! [[ "$SKILL_NAME" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
    log_error "Invalid skill name format. Use lowercase letters, numbers, and hyphens only."
    log_error "Examples: 'docker-fixes', 'api-patterns', 'pnpm-setup'"
    exit 1
fi

# Validate output path to avoid writes outside current workspace.
if [[ "$SKILLS_DIR" = /* ]]; then
    log_error "Output directory must be a relative path under the current directory."
    exit 1
fi

if [[ "$SKILLS_DIR" =~ (^|/)\.\.(/|$) ]]; then
    log_error "Output directory cannot include '..' path segments."
    exit 1
fi

SKILLS_DIR="SKILLS_DIR#./"
SKILLS_DIR="./$SKILLS_DIR"

SKILL_PATH="$SKILLS_DIR/$SKILL_NAME"

# Check if skill already exists
if [ -d "$SKILL_PATH" ] && [ "$DRY_RUN" = false ]; then
    log_error "Skill already exists: $SKILL_PATH"
    log_error "Use a different name or remove the existing skill first."
    exit 1
fi

# Dry run output
if [ "$DRY_RUN" = true ]; then
    log_info "Dry run - would create:"
    echo "  $SKILL_PATH/"
    echo "  $SKILL_PATH/SKILL.md"
    echo ""
    echo "Template content would be:"
    echo "---"
    cat << TEMPLATE
name: $SKILL_NAME
description: "[TODO: Add a concise description of what this skill does and when to use it]"
---

# $(echo "$SKILL_NAME" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1')

[TODO: Brief introduction explaining the skill's purpose]

## Quick Reference

| Situation | Action |
|-----------|--------|
| [Trigger condition] | [What to do] |

## Usage

[TODO: Detailed usage instructions]

## Examples

[TODO: Add concrete examples]

## Source Learning

This skill was extracted from a learning entry.
- Learning ID: [TODO: Add original learning ID]
- Original File: .learnings/LEARNINGS.md
TEMPLATE
    echo "---"
    exit 0
fi

# Create skill directory structure
log_info "Creating skill: $SKILL_NAME"

mkdir -p "$SKILL_PATH"

# Create SKILL.md from template
cat > "$SKILL_PATH/SKILL.md" << TEMPLATE
---
name: $SKILL_NAME
description: "[TODO: Add a concise description of what this skill does and when to use it]"
---

# $(echo "$SKILL_NAME" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1')

[TODO: Brief introduction explaining the skill's purpose]

## Quick Reference

| Situation | Action |
|-----------|--------|
| [Trigger condition] | [What to do] |

## Usage

[TODO: Detailed usage instructions]

## Examples

[TODO: Add concrete examples]

## Source Learning

This skill was extracted from a learning entry.
- Learning ID: [TODO: Add original learning ID]
- Original File: .learnings/LEARNINGS.md
TEMPLATE

log_info "Created: $SKILL_PATH/SKILL.md"

# Suggest next steps
echo ""
log_info "Skill scaffold created successfully!"
echo ""
echo "Next steps:"
echo "  1. Edit $SKILL_PATH/SKILL.md"
echo "  2. Fill in the TODO sections with content from your learning"
echo "  3. Add references/ folder if you have detailed documentation"
echo "  4. Add scripts/ folder if you have executable code"
echo "  5. Update the original learning entry with:"
echo "     **Status**: promoted_to_skill"
echo "     **Skill-Path**: skills/$SKILL_NAME"

FILE:scripts/error-detector.sh
#!/bin/bash
# Self-Improvement Error Detector Hook
# Triggers on PostToolUse for Bash to detect command failures
# Reads CLAUDE_TOOL_OUTPUT environment variable

set -e

# Check if tool output indicates an error
# CLAUDE_TOOL_OUTPUT contains the result of the tool execution
OUTPUT="-"

# Patterns indicating errors (case-insensitive matching)
ERROR_PATTERNS=(
    "error:"
    "Error:"
    "ERROR:"
    "failed"
    "FAILED"
    "command not found"
    "No such file"
    "Permission denied"
    "fatal:"
    "Exception"
    "Traceback"
    "npm ERR!"
    "ModuleNotFoundError"
    "SyntaxError"
    "TypeError"
    "exit code"
    "non-zero"
)

# Check if output contains any error pattern
contains_error=false
for pattern in "ERROR_PATTERNS[@]"; do
    if [[ "$OUTPUT" == *"$pattern"* ]]; then
        contains_error=true
        break
    fi
done

# Only output reminder if error detected
if [ "$contains_error" = true ]; then
    cat << 'EOF'
<error-detected>
A command error was detected. Consider logging this to .learnings/ERRORS.md if:
- The error was unexpected or non-obvious
- It required investigation to resolve
- It might recur in similar contexts
- The solution could benefit future sessions

Use the self-improvement skill format: [ERR-YYYYMMDD-XXX]
</error-detected>
EOF
fi

FILE:hooks/openclaw/handler.js
/**
 * Self-Improvement Hook for OpenClaw
 * 
 * Injects a reminder to evaluate learnings during agent bootstrap.
 * Fires on agent:bootstrap event before workspace files are injected.
 */

const REMINDER_CONTENT = `
## Self-Improvement Reminder

After completing tasks, evaluate if any learnings should be captured:

**Log when:**
- User corrects you → \`.learnings/LEARNINGS.md\`
- Command/operation fails → \`.learnings/ERRORS.md\`
- User wants missing capability → \`.learnings/FEATURE_REQUESTS.md\`
- You discover your knowledge was wrong → \`.learnings/LEARNINGS.md\`
- You find a better approach → \`.learnings/LEARNINGS.md\`

**Promote when pattern is proven:**
- Behavioral patterns → \`SOUL.md\`
- Workflow improvements → \`AGENTS.md\`
- Tool gotchas → \`TOOLS.md\`

Keep entries simple: date, title, what happened, what to do differently.
`.trim();

const handler = async (event) => {
  // Safety checks for event structure
  if (!event || typeof event !== 'object') {
    return;
  }

  // Only handle agent:bootstrap events
  if (event.type !== 'agent' || event.action !== 'bootstrap') {
    return;
  }

  // Safety check for context
  if (!event.context || typeof event.context !== 'object') {
    return;
  }

  // Inject the reminder as a virtual bootstrap file
  // Check that bootstrapFiles is an array before pushing
  if (Array.isArray(event.context.bootstrapFiles)) {
    event.context.bootstrapFiles.push({
      path: 'SELF_IMPROVEMENT_REMINDER.md',
      content: REMINDER_CONTENT,
      virtual: true,
    });
  }
};

module.exports = handler;
module.exports.default = handler;

FILE:hooks/openclaw/HOOK.md
---
name: self-improvement
description: "Injects self-improvement reminder during agent bootstrap"
metadata: {"openclaw":{"emoji":"🧠","events":["agent:bootstrap"]}}
---

# Self-Improvement Hook

Injects a reminder to evaluate learnings during agent bootstrap.

## What It Does

- Fires on `agent:bootstrap` (before workspace files are injected)
- Adds a reminder block to check `.learnings/` for relevant entries
- Prompts the agent to log corrections, errors, and discoveries

## Configuration

No configuration needed. Enable with:

```bash
openclaw hooks enable self-improvement
```

FILE:hooks/openclaw/handler.ts
/**
 * Self-Improvement Hook for OpenClaw
 * 
 * Injects a reminder to evaluate learnings during agent bootstrap.
 * Fires on agent:bootstrap event before workspace files are injected.
 */

import type { HookHandler } from 'openclaw/hooks';

const REMINDER_CONTENT = `## Self-Improvement Reminder

After completing tasks, evaluate if any learnings should be captured:

**Log when:**
- User corrects you → \`.learnings/LEARNINGS.md\`
- Command/operation fails → \`.learnings/ERRORS.md\`
- User wants missing capability → \`.learnings/FEATURE_REQUESTS.md\`
- You discover your knowledge was wrong → \`.learnings/LEARNINGS.md\`
- You find a better approach → \`.learnings/LEARNINGS.md\`

**Promote when pattern is proven:**
- Behavioral patterns → \`SOUL.md\`
- Workflow improvements → \`AGENTS.md\`
- Tool gotchas → \`TOOLS.md\`

Keep entries simple: date, title, what happened, what to do differently.`;

const handler: HookHandler = async (event) => {
  // Safety checks for event structure
  if (!event || typeof event !== 'object') {
    return;
  }

  // Only handle agent:bootstrap events
  if (event.type !== 'agent' || event.action !== 'bootstrap') {
    return;
  }

  // Safety check for context
  if (!event.context || typeof event.context !== 'object') {
    return;
  }

  // Skip sub-agent sessions to avoid bootstrap issues
  // Sub-agents have sessionKey patterns like "agent:main:subagent:..."
  const sessionKey = event.sessionKey || '';
  if (sessionKey.includes(':subagent:')) {
    return;
  }

  // Inject the reminder as a virtual bootstrap file
  // Check that bootstrapFiles is an array before pushing
  if (Array.isArray(event.context.bootstrapFiles)) {
    event.context.bootstrapFiles.push({
      path: 'SELF_IMPROVEMENT_REMINDER.md',
      content: REMINDER_CONTENT,
      virtual: true,
    });
  }
};

export default handler;

FILE:references/examples.md
# Entry Examples

Concrete examples of well-formatted entries with all fields.

## Learning: Correction

```markdown
## [LRN-20250115-001] correction

**Logged**: 2025-01-15T10:30:00Z
**Priority**: high
**Status**: pending
**Area**: tests

### Summary
Incorrectly assumed pytest fixtures are scoped to function by default

### Details
When writing test fixtures, I assumed all fixtures were function-scoped. 
User corrected that while function scope is the default, the codebase 
convention uses module-scoped fixtures for database connections to 
improve test performance.

### Suggested Action
When creating fixtures that involve expensive setup (DB, network), 
check existing fixtures for scope patterns before defaulting to function scope.

### Metadata
- Source: user_feedback
- Related Files: tests/conftest.py
- Tags: pytest, testing, fixtures

---
```

## Learning: Knowledge Gap (Resolved)

```markdown
## [LRN-20250115-002] knowledge_gap

**Logged**: 2025-01-15T14:22:00Z
**Priority**: medium
**Status**: resolved
**Area**: config

### Summary
Project uses pnpm not npm for package management

### Details
Attempted to run `npm install` but project uses pnpm workspaces.
Lock file is `pnpm-lock.yaml`, not `package-lock.json`.

### Suggested Action
Check for `pnpm-lock.yaml` or `pnpm-workspace.yaml` before assuming npm.
Use `pnpm install` for this project.

### Metadata
- Source: error
- Related Files: pnpm-lock.yaml, pnpm-workspace.yaml
- Tags: package-manager, pnpm, setup

### Resolution
- **Resolved**: 2025-01-15T14:30:00Z
- **Commit/PR**: N/A - knowledge update
- **Notes**: Added to CLAUDE.md for future reference

---
```

## Learning: Promoted to CLAUDE.md

```markdown
## [LRN-20250115-003] best_practice

**Logged**: 2025-01-15T16:00:00Z
**Priority**: high
**Status**: promoted
**Promoted**: CLAUDE.md
**Area**: backend

### Summary
API responses must include correlation ID from request headers

### Details
All API responses should echo back the X-Correlation-ID header from 
the request. This is required for distributed tracing. Responses 
without this header break the observability pipeline.

### Suggested Action
Always include correlation ID passthrough in API handlers.

### Metadata
- Source: user_feedback
- Related Files: src/middleware/correlation.ts
- Tags: api, observability, tracing

---
```

## Learning: Promoted to AGENTS.md

```markdown
## [LRN-20250116-001] best_practice

**Logged**: 2025-01-16T09:00:00Z
**Priority**: high
**Status**: promoted
**Promoted**: AGENTS.md
**Area**: backend

### Summary
Must regenerate API client after OpenAPI spec changes

### Details
When modifying API endpoints, the TypeScript client must be regenerated.
Forgetting this causes type mismatches that only appear at runtime.
The generate script also runs validation.

### Suggested Action
Add to agent workflow: after any API changes, run `pnpm run generate:api`.

### Metadata
- Source: error
- Related Files: openapi.yaml, src/client/api.ts
- Tags: api, codegen, typescript

---
```

## Error Entry

```markdown
## [ERR-20250115-A3F] docker_build

**Logged**: 2025-01-15T09:15:00Z
**Priority**: high
**Status**: pending
**Area**: infra

### Summary
Docker build fails on M1 Mac due to platform mismatch

### Error
```
error: failed to solve: python:3.11-slim: no match for platform linux/arm64
```

### Context
- Command: `docker build -t myapp .`
- Dockerfile uses `FROM python:3.11-slim`
- Running on Apple Silicon (M1/M2)

### Suggested Fix
Add platform flag: `docker build --platform linux/amd64 -t myapp .`
Or update Dockerfile: `FROM --platform=linux/amd64 python:3.11-slim`

### Metadata
- Reproducible: yes
- Related Files: Dockerfile

---
```

## Error Entry: Recurring Issue

```markdown
## [ERR-20250120-B2C] api_timeout

**Logged**: 2025-01-20T11:30:00Z
**Priority**: critical
**Status**: pending
**Area**: backend

### Summary
Third-party payment API timeout during checkout

### Error
```
TimeoutError: Request to payments.example.com timed out after 30000ms
```

### Context
- Command: POST /api/checkout
- Timeout set to 30s
- Occurs during peak hours (lunch, evening)

### Suggested Fix
Implement retry with exponential backoff. Consider circuit breaker pattern.

### Metadata
- Reproducible: yes (during peak hours)
- Related Files: src/services/payment.ts
- See Also: ERR-20250115-X1Y, ERR-20250118-Z3W

---
```

## Feature Request

```markdown
## [FEAT-20250115-001] export_to_csv

**Logged**: 2025-01-15T16:45:00Z
**Priority**: medium
**Status**: pending
**Area**: backend

### Requested Capability
Export analysis results to CSV format

### User Context
User runs weekly reports and needs to share results with non-technical 
stakeholders in Excel. Currently copies output manually.

### Complexity Estimate
simple

### Suggested Implementation
Add `--output csv` flag to the analyze command. Use standard csv module.
Could extend existing `--output json` pattern.

### Metadata
- Frequency: recurring
- Related Features: analyze command, json output

---
```

## Feature Request: Resolved

```markdown
## [FEAT-20250110-002] dark_mode

**Logged**: 2025-01-10T14:00:00Z
**Priority**: low
**Status**: resolved
**Area**: frontend

### Requested Capability
Dark mode support for the dashboard

### User Context
User works late hours and finds the bright interface straining.
Several other users have mentioned this informally.

### Complexity Estimate
medium

### Suggested Implementation
Use CSS variables for colors. Add toggle in user settings.
Consider system preference detection.

### Metadata
- Frequency: recurring
- Related Features: user settings, theme system

### Resolution
- **Resolved**: 2025-01-18T16:00:00Z
- **Commit/PR**: #142
- **Notes**: Implemented with system preference detection and manual toggle

---
```

## Learning: Promoted to Skill

```markdown
## [LRN-20250118-001] best_practice

**Logged**: 2025-01-18T11:00:00Z
**Priority**: high
**Status**: promoted_to_skill
**Skill-Path**: skills/docker-m1-fixes
**Area**: infra

### Summary
Docker build fails on Apple Silicon due to platform mismatch

### Details
When building Docker images on M1/M2 Macs, the build fails because
the base image doesn't have an ARM64 variant. This is a common issue
that affects many developers.

### Suggested Action
Add `--platform linux/amd64` to docker build command, or use
`FROM --platform=linux/amd64` in Dockerfile.

### Metadata
- Source: error
- Related Files: Dockerfile
- Tags: docker, arm64, m1, apple-silicon
- See Also: ERR-20250115-A3F, ERR-20250117-B2D

---
```

## Extracted Skill Example

When the above learning is extracted as a skill, it becomes:

**File**: `skills/docker-m1-fixes/SKILL.md`

```markdown
---
name: docker-m1-fixes
description: "Fixes Docker build failures on Apple Silicon (M1/M2). Use when docker build fails with platform mismatch errors."
---

# Docker M1 Fixes

Solutions for Docker build issues on Apple Silicon Macs.

## Quick Reference

| Error | Fix |
|-------|-----|
| `no match for platform linux/arm64` | Add `--platform linux/amd64` to build |
| Image runs but crashes | Use emulation or find ARM-compatible base |

## The Problem

Many Docker base images don't have ARM64 variants. When building on
Apple Silicon (M1/M2/M3), Docker attempts to pull ARM64 images by
default, causing platform mismatch errors.

## Solutions

### Option 1: Build Flag (Recommended)

Add platform flag to your build command:

\`\`\`bash
docker build --platform linux/amd64 -t myapp .
\`\`\`

### Option 2: Dockerfile Modification

Specify platform in the FROM instruction:

\`\`\`dockerfile
FROM --platform=linux/amd64 python:3.11-slim
\`\`\`

### Option 3: Docker Compose

Add platform to your service:

\`\`\`yaml
services:
  app:
    platform: linux/amd64
    build: .
\`\`\`

## Trade-offs

| Approach | Pros | Cons |
|----------|------|------|
| Build flag | No file changes | Must remember flag |
| Dockerfile | Explicit, versioned | Affects all builds |
| Compose | Convenient for dev | Requires compose |

## Performance Note

Running AMD64 images on ARM64 uses Rosetta 2 emulation. This works
for development but may be slower. For production, find ARM-native
alternatives when possible.

## Source

- Learning ID: LRN-20250118-001
- Category: best_practice
- Extraction Date: 2025-01-18
```

FILE:references/openclaw-integration.md
# OpenClaw Integration

Complete setup and usage guide for integrating the self-improvement skill with OpenClaw.

## Overview

OpenClaw uses workspace-based prompt injection combined with event-driven hooks. Context is injected from workspace files at session start, and hooks can trigger on lifecycle events.

## Workspace Structure

```
~/.openclaw/                      
├── workspace/                   # Working directory
│   ├── AGENTS.md               # Multi-agent coordination patterns
│   ├── SOUL.md                 # Behavioral guidelines and personality
│   ├── TOOLS.md                # Tool capabilities and gotchas
│   ├── MEMORY.md               # Long-term memory (main session only)
│   └── memory/                 # Daily memory files
│       └── YYYY-MM-DD.md
├── skills/                      # Installed skills
│   └── <skill-name>/
│       └── SKILL.md
└── hooks/                       # Custom hooks
    └── <hook-name>/
        ├── HOOK.md
        └── handler.ts
```

## Quick Setup

### 1. Install the Skill

```bash
clawdhub install self-improving-agent
```

Or copy manually:

```bash
cp -r self-improving-agent ~/.openclaw/skills/
```

### 2. Install the Hook (Optional)

Copy the hook to OpenClaw's hooks directory:

```bash
cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement
```

Enable the hook:

```bash
openclaw hooks enable self-improvement
```

### 3. Create Learning Files

Create the `.learnings/` directory in your workspace:

```bash
mkdir -p ~/.openclaw/workspace/.learnings
```

Or in the skill directory:

```bash
mkdir -p ~/.openclaw/skills/self-improving-agent/.learnings
```

## Injected Prompt Files

### AGENTS.md

Purpose: Multi-agent workflows and delegation patterns.

```markdown
# Agent Coordination

## Delegation Rules
- Use explore agent for open-ended codebase questions
- Spawn sub-agents for long-running tasks
- Use sessions_send for cross-session communication

## Session Handoff
When delegating to another session:
1. Provide full context in the handoff message
2. Include relevant file paths
3. Specify expected output format
```

### SOUL.md

Purpose: Behavioral guidelines and communication style.

```markdown
# Behavioral Guidelines

## Communication Style
- Be direct and concise
- Avoid unnecessary caveats and disclaimers
- Use technical language appropriate to context

## Error Handling
- Admit mistakes promptly
- Provide corrected information immediately
- Log significant errors to learnings
```

### TOOLS.md

Purpose: Tool capabilities, integration gotchas, local configuration.

```markdown
# Tool Knowledge

## Self-Improvement Skill
Log learnings to `.learnings/` for continuous improvement.

## Local Tools
- Document tool-specific gotchas here
- Note authentication requirements
- Track integration quirks
```

## Learning Workflow

### Capturing Learnings

1. **In-session**: Log to `.learnings/` as usual
2. **Cross-session**: Promote to workspace files

### Promotion Decision Tree

```
Is the learning project-specific?
├── Yes → Keep in .learnings/
└── No → Is it behavioral/style-related?
    ├── Yes → Promote to SOUL.md
    └── No → Is it tool-related?
        ├── Yes → Promote to TOOLS.md
        └── No → Promote to AGENTS.md (workflow)
```

### Promotion Format Examples

**From learning:**
> Git push to GitHub fails without auth configured - triggers desktop prompt

**To TOOLS.md:**
```markdown
## Git
- Don't push without confirming auth is configured
- Use `gh auth status` to check GitHub CLI auth
```

## Inter-Agent Communication

OpenClaw provides tools for cross-session communication:

### sessions_list

View active and recent sessions:
```
sessions_list(activeMinutes=30, messageLimit=3)
```

### sessions_history

Read transcript from another session:
```
sessions_history(sessionKey="session-id", limit=50)
```

### sessions_send

Send message to another session:
```
sessions_send(sessionKey="session-id", message="Learning: API requires X-Custom-Header")
```

### sessions_spawn

Spawn a background sub-agent:
```
sessions_spawn(task="Research X and report back", label="research")
```

## Available Hook Events

| Event | When It Fires |
|-------|---------------|
| `agent:bootstrap` | Before workspace files inject |
| `command:new` | When `/new` command issued |
| `command:reset` | When `/reset` command issued |
| `command:stop` | When `/stop` command issued |
| `gateway:startup` | When gateway starts |

## Detection Triggers

### Standard Triggers
- User corrections ("No, that's wrong...")
- Command failures (non-zero exit codes)
- API errors
- Knowledge gaps

### OpenClaw-Specific Triggers

| Trigger | Action |
|---------|--------|
| Tool call error | Log to TOOLS.md with tool name |
| Session handoff confusion | Log to AGENTS.md with delegation pattern |
| Model behavior surprise | Log to SOUL.md with expected vs actual |
| Skill issue | Log to .learnings/ or report upstream |

## Verification

Check hook is registered:

```bash
openclaw hooks list
```

Check skill is loaded:

```bash
openclaw status
```

## Troubleshooting

### Hook not firing

1. Ensure hooks enabled in config
2. Restart gateway after config changes
3. Check gateway logs for errors

### Learnings not persisting

1. Verify `.learnings/` directory exists
2. Check file permissions
3. Ensure workspace path is configured correctly

### Skill not loading

1. Check skill is in skills directory
2. Verify SKILL.md has correct frontmatter
3. Run `openclaw status` to see loaded skills

FILE:references/hooks-setup.md
# Hook Setup Guide

Configure automatic self-improvement triggers for AI coding agents.

## Overview

Hooks enable proactive learning capture by injecting reminders at key moments:
- **UserPromptSubmit**: Reminder after each prompt to evaluate learnings
- **PostToolUse (Bash)**: Error detection when commands fail

## Claude Code Setup

### Option 1: Project-Level Configuration

Create `.claude/settings.json` in your project root:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "./skills/self-improvement/scripts/activator.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./skills/self-improvement/scripts/error-detector.sh"
          }
        ]
      }
    ]
  }
}
```

### Option 2: User-Level Configuration

Add to `~/.claude/settings.json` for global activation:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/skills/self-improvement/scripts/activator.sh"
          }
        ]
      }
    ]
  }
}
```

### Minimal Setup (Activator Only)

For lower overhead, use only the UserPromptSubmit hook:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "./skills/self-improvement/scripts/activator.sh"
          }
        ]
      }
    ]
  }
}
```

## Codex CLI Setup

Codex uses the same hook system as Claude Code. Create `.codex/settings.json`:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "./skills/self-improvement/scripts/activator.sh"
          }
        ]
      }
    ]
  }
}
```

## GitHub Copilot Setup

Copilot doesn't support hooks directly. Instead, add guidance to `.github/copilot-instructions.md`:

```markdown
## Self-Improvement

After completing tasks that involved:
- Debugging non-obvious issues
- Discovering workarounds
- Learning project-specific patterns
- Resolving unexpected errors

Consider logging the learning to `.learnings/` using the format from the self-improvement skill.

For high-value learnings that would benefit other sessions, consider skill extraction.
```

## Verification

### Test Activator Hook

1. Enable the hook configuration
2. Start a new Claude Code session
3. Send any prompt
4. Verify you see `<self-improvement-reminder>` in the context

### Test Error Detector Hook

1. Enable PostToolUse hook for Bash
2. Run a command that fails: `ls /nonexistent/path`
3. Verify you see `<error-detected>` reminder

### Dry Run Extract Script

```bash
./skills/self-improvement/scripts/extract-skill.sh test-skill --dry-run
```

Expected output shows the skill scaffold that would be created.

## Troubleshooting

### Hook Not Triggering

1. **Check script permissions**: `chmod +x scripts/*.sh`
2. **Verify path**: Use absolute paths or paths relative to project root
3. **Check settings location**: Project vs user-level settings
4. **Restart session**: Hooks are loaded at session start

### Permission Denied

```bash
chmod +x ./skills/self-improvement/scripts/activator.sh
chmod +x ./skills/self-improvement/scripts/error-detector.sh
chmod +x ./skills/self-improvement/scripts/extract-skill.sh
```

### Script Not Found

If using relative paths, ensure you're in the correct directory or use absolute paths:

```json
{
  "command": "/absolute/path/to/skills/self-improvement/scripts/activator.sh"
}
```

### Too Much Overhead

If the activator feels intrusive:

1. **Use minimal setup**: Only UserPromptSubmit, skip PostToolUse
2. **Add matcher filter**: Only trigger for certain prompts:

```json
{
  "matcher": "fix|debug|error|issue",
  "hooks": [...]
}
```

## Hook Output Budget

The activator is designed to be lightweight:
- **Target**: ~50-100 tokens per activation
- **Content**: Structured reminder, not verbose instructions
- **Format**: XML tags for easy parsing

If you need to reduce overhead further, you can edit `activator.sh` to output less text.

## Security Considerations

- Hook scripts run with the same permissions as Claude Code
- Scripts only output text; they don't modify files or run commands
- Error detector reads `CLAUDE_TOOL_OUTPUT` environment variable
- All scripts are opt-in (you must configure them explicitly)

## Disabling Hooks

To temporarily disable without removing configuration:

1. **Comment out in settings**:
```json
{
  "hooks": {
    // "UserPromptSubmit": [...]
  }
}
```

2. **Or delete the settings file**: Hooks won't run without configuration