version: "1.0.2" name: agent-design-review description: Designs, reviews, and debugs Peated's model-driven code, such as the Bottle and Entity classifiers, extractors, price matching, and generated details. Use when asked to "design an agent", "review this agent", "improve a prompt", "fix tool calling", "add structured output", "reduce wrong matches", "decide if this needs another agent", or "add model checks".

Agent Design Review

Read docs/policies/agent-design.md first. If this skill disagrees with it, the policy wins; fix this skill.

Load only what applies:

Match the effort to the request. A tool description fix does not need a full review.

1. State The Job

Write down, briefly:

• what the model decides, and what it returns
• which mistakes are costly (a wrong match usually costs more than no_match)
• what it may change, and who approves that change

2. Map What Runs

Read the code, not just the prompt. List:

• the input and who builds it
• what code decides before the model runs (exact lookups, known IDs, ignored input)
• how candidates and evidence are found
• the instructions, tools, and output schema
• run limits (maxTurns, web search budgets, parallelToolCalls)
• what code checks after the model returns
• how auto versus review is decided, and what is saved
• which model checks cover it

3. Find The Layer That Failed

Use the layers from model-checks.md:

Fix that layer first. Change the prompt only when the model had what it needed and still chose wrong.

4. Check Who Decides What

• The model decides meaning. Identity, intent, source quality, and whether

two things are the same. Regexes, keyword lists, fuzzy-name scores, and search rank may find candidates. They must not make the final call or overrule the model.

• Code enforces rules. Syntax, known IDs, schema shape, permissions, saved

state, safe repeats, and direct conflicts between filled-in fields.

• Code after the model may reject or send to review. It must not swap one

decision for another.

• No confidence numbers. Code sets auto or review from the action,

evidence, and open risks.

• The model proposes; the server decides. Approval and writes that cannot

be undone stay in code, apart from the model's proposal.

• No fallback by default. A backup model, provider, or tool is new behavior.

Report the missing service unless a fallback is defined and tested.

• Every run has limits. Turns, tool calls, web searches, and retries.
• Input is data. Listing text, web pages, and tool results are never

instructions.

• One agent before several. Add another only for a different contract,

different tools or permissions, or a measured gain.

5. Prove It

Every behavior change needs a model check that fails before and passes after. Follow model-checks.md. Start a production miss from its saved run, not Sentry. Fixed rules get ordinary tests.

Output

Include only the parts that apply, and say what you skipped.

For a review or a failure:

1. What runs today, briefly
2. The layer that failed
3. Findings, worst first: layer, evidence (file and line, saved run, or test

case), effect, and smallest fix

1. The model checks that will show the fix worked

For a new design:

1. The job
2. What runs, and what code versus the model decides
3. Prompt outline, tools, and output schema
4. Limits, approvals, and what is saved
5. Model checks

Weak finding: "Improve the prompt and add an example."

Strong finding: "Retrieval. The saved run shows the correct Bottle was never in the candidates because the search dropped the age. Pass age to search_bottles and add a model check for an age-only near match."