Agent Patterns

Reflexion (Shinn et al., 2023 — A1.2)

Executor prompt checklist (iteration 2+):

• Instruction to read ## Previous Attempts in TASK_CONTEXT.md before touching files
• Instruction to explicitly acknowledge each BLOCKER/WARNING before acting
• TASK_CONTEXT.md path passed as argument — NOT the content inlined into the prompt

Orchestrator checklist:

• Append critic findings verbatim to ## Previous Attempts (no paraphrase — A1.6)
• Pass file path, not inline findings
• Counter: if iteration == 5 and no APPROVE → escalate NEEDS_HUMAN

Red flags:

• Executor repeats the same mistake on iter 2 → ## Previous Attempts missing or skipped
• Orchestrator summarises critic findings for the executor → violates no-paraphrase rule
• TASK_CONTEXT.md is gitignored (session file) but orchestrator tries to commit it → see AGENTS.md

Critic Isolation / LLM-as-Judge (Zheng et al., 2023 — A1.2; A1.6)

Critic must receive ONLY:

• Original user task text — verbatim, not paraphrased
• Acceptance criteria
• Executor's final output or precise summary of changed files

Critic must NOT receive:

• Executor's reasoning or chain-of-thought
• Conversation history or orchestrator commentary
• Previous iteration context
• Orchestrator's interpretation or summary of the task

Why: executor reasoning causes anchoring bias → critic evaluates the reasoning path, not the result.

Red flag: critic returns APPROVE on a clearly incomplete result → likely received executor reasoning, not just output.

Constitutional AI / Rubric Design (Anthropic, 2022 — A1.2, A1.4)

Severity definitions:

Rubric calibration checklist:

• Is the rule testable by a critic with read-only tools?
• Is the BLOCKER threshold proportional to the cost of the mistake?
• Does the rubric have at least one golden test per BLOCKER category?
• After changing a rubric: run golden tests before merging (A1.5, eval-before-merge)

ACKNOWLEDGED pattern (SUGGESTION-only):

ACKNOWLEDGED: SUGGESTION | <category> | <file/section> | <issue> | Deferred: <reason>

Critic must honour this on next review — do not re-raise as WARNING/BLOCKER.

Plan-and-Execute Decomposition (Wang et al., 2023 — A1.2)

Checklist:

• Max 6 subtasks per task
• Each subtask: deliverable, verification method, executor + critic assigned
• Subtasks ordered by dependency (dependent subtask waits for APPROVE on prerequisite)
• Fast-track applied where eligible (analysis/audit, docs-only, agent-prompt-change)

Anti-patterns:

• Single subtask "do everything" → executor scope creep, critic unfocused verdict
• Subtasks not ordered → executor B edits file that executor A hasn't finished yet
• No verification method → orchestrator can't determine APPROVE criteria

Context Engineering (A1.6 derived principle)

Rule: no more context than needed.

Violation signals:

• Prompt >~3000 tokens before the actual task → trim
• Executor pastes full file "for context" → scope creep
• Critic receives executor chain-of-thought → isolation violation

Self-Refine Finding Format (Madaan et al., 2023 — A1.2)

Every critic finding must have all three:

1. Location — file path or section name
2. Root cause — why this is a problem
3. Actionable fix — exactly what to change

❌ Bad: WARNING: unclear prose in §3.2 ✅ Good: WARNING §3.2 "Iteration rules": "iterate as needed" has no termination condition → specify max_iterations: 5 per AutoGen pattern

References

• framework/spec/appendices/01-appendix-a1-ai-and-llm-standards.md — A1.2, A1.6
• AGENTS.md — Execution Workflow
• framework/00-multi-agent-development-spec.md — §3 Critique rubrics