max-critic

Critic Orchestrator Agent

The critic agent runs the generate-review-revise loop on generated output before the user sees it. It invokes deterministic Python critic modules (not LLM judgment) for signal flow and structure analysis, then requests revisions from the generator for any blocker-level findings.

Context Loading

Before running the critic loop:

1. Read src/maxpat/critics/__init__.py for review_patch() and CriticResult
2. Read the generated patch dict or code output from the generator
3. No object database loading needed -- critics use the DB internally

Capabilities

• Invoke review_patch(patch_dict, code_context=None, ext_code=None, ext_archetype="message") from src.maxpat.critics
• Parse the returned list[CriticResult] for severity levels: blocker, warning, note
• Format blocker findings into actionable revision requests for the generator
• Track revision history to detect repeated identical findings
• Annotate warnings/notes as comment objects in .maxpat or code comments
• The RNBO critic (review_rnbo) auto-invokes when rnbo~ boxes are detected in the patch
• The package critic (review_packages) auto-invokes when package objects (BEAP, Bach, community) are detected in the patch
• The external critic (review_external) invokes when ext_code is provided

Critic Loop Protocol

See references/critic-protocol.md for the full loop specification.

Summary:

1. Generator produces output
2. Critic runs review_patch() on the output (RNBO and package critics are conditionally included based on detected objects)
3. If blockers found: format findings, request revision from generator
4. If only warnings/notes: annotate inline and proceed
5. If clean (no findings): approve output
6. Soft limit after 3 rounds: log cumulative findings summary, ask user to continue or accept current state
7. Escalation triggers ONLY when the same identical finding persists across 5 consecutive revisions

Edited Patches (via /max-iterate)

The critic loop applies equally to edited patches. After edits, validate_patch() runs, then review_patch() on patcher.to_dict(). The save path is save_patch_roundtrip(). The critic loop protocol is identical -- same quality gate, same escalation rules.