Agent Design Review

Agent Design Review

Design or review agents by identifying the success contract first, mapping the real execution path second, and changing the smallest layer that is actually causing failures.

Load only what applies:

Step 1: Set Mode and Success Contract

Set the task mode first:

• design: a new agent or major redesign
• review: assess an existing agent and prioritize changes
• debug: explain why a current agent is failing and what to change first

Then write a short success contract:

• task the system must complete
• target quality or success metric
• unacceptable failures
• cost and latency budget
• operator or reviewer load constraints
• side effects the system may take
• tools, data sources, and approvals available
• current eval status

If the user asks only for a prompt rewrite, still check whether retrieval, tools, thresholds, or runtime policy dominate the failures.

Step 2: Choose the Smallest Architecture That Works

Use references/principles.md.

Classify the system before proposing changes:

Prefer deterministic preprocessing, retrieval, routing, or thresholds before adding more agent autonomy.

Step 3: Map the Real Execution Path

Write an execution-path summary that names:

• static instructions
• dynamic request context
• deterministic preprocessing and normalization
• retrieval or candidate generation
• tool list and tool descriptions
• loop and stop conditions
• final output schema
• post-model validation or sanitization
• automation thresholds and approval gates
• current evals, traces, tests, or queue feedback

For classifier-style systems, separate deterministic stages from model-driven stages. Do not review only the prompt if code outside the prompt decides most of the behavior.

Step 4: Identify the Primary Bottleneck

Inspect the highest-risk layer first:

Do not default to prompt rewrites if retrieval, thresholds, or post-model guards dominate the failures.

Step 5: Follow the Relevant Review or Design Path

Review or Debug Path

1. Summarize the execution path.
2. Name the primary bottleneck.
3. Report findings ordered by severity.
4. Recommend the smallest effective changes first.
5. Add an eval plan that can prove whether the changes helped.

For each finding, include:

• layer
• evidence from prompt, tools, code, traces, or tests
• likely impact on quality, cost, or operator load
• smallest effective change

Design Path

1. Define the success contract.
2. Justify the architecture choice.
3. Draft a stable prompt template.
4. Define tool contracts and typed outputs.
5. Define loop policy, approvals, and fallback behavior.
6. Define the eval plan before extensive iteration.

If you write a prompt, return a cache-friendly prompt skeleton with clear slots for dynamic inputs rather than an unstructured wall of text. If you write tool schemas, return concrete schema drafts with parameter descriptions, enums, and required fields instead of only high-level advice.

Output Format

When reviewing or debugging, produce:

1. Success contract
2. Execution-path summary
3. Architecture verdict
4. Primary bottleneck
5. Findings
6. Suggested changes
7. Eval plan

When designing, produce:

1. Success contract
2. Proposed execution path
3. Architecture rationale
4. Prompt skeleton
5. Tool and schema design
6. Runtime policy and guardrails
7. Eval plan

Exit Criteria

The work is complete only when:

• the success contract is explicit
• the architecture choice is justified
• the biggest likely bottleneck is named
• prompt, tools, outputs, runtime, boundaries, and eval gaps are each addressed or explicitly ruled out
• recommendations are ordered from smallest effective change to larger redesign
• the eval plan can measure improvement