quality-loop

# Bounded Quality Loop Turn the user's request into a temporary, request-specific workflow. Preserve the user's subject, constraints, and desired output rather than replacing them with a fixed example. ## Process 1. Create a writer role that produces the requested deliverable. 2. Create a separate reviewer role. Give it the original request and the latest draft. On later reviews, also give it the previous required feedback so it can verify that the revision addressed those items. The writer must not review its own work. 3. Ask the reviewer for structured output using a small object schema: - `approved`: required boolean - `feedback`: required array containing only changes that must be made - no additional properties 4. If the user did not provide factual values such as dates, URLs, or contacts, accept clear placeholders. Do not reject solely because those values are not concrete, and do not ask the writer to invent them. Check that the placeholders are clear and the required fields or steps are complete. 5. Treat the result as approved only when `approved` is true and `feedback` is empty. If the fields disagree, the feedback wins. 6. If approved, stop immediately. If the reviewer rejects without actionable feedback, stop as unapproved instead of asking for an empty revision. 7. Otherwise, if another review is still available, pass the complete latest draft and every feedback item to the writer, then review the revision again. 8. Allow at most three reviews. After the third rejected review, stop without creating an unreviewed revision. This keeps the remaining feedback aligned with the returned draft. 9. Return the latest reviewed draft, approval status, number of reviews, and any remaining feedback. ## Illustrative workflow shape Keep the loop explicit and bounded; the request supplies the actual content and criteria. ```python review_schema = { "type": "object", "properties": { "approved": {"type": "boolean"}, "feedback": {"type": "array", "items": {"type": "string"}}, }, "required": ["approved", "feedback"], "additionalProperties": False, } draft = await agent(request, instruction="Write the first draft.", tools=[]) previous_feedback = [] for attempt in range(1, 4): review = await agent( { "request": request, "draft": draft["text"], "previous_feedback": previous_feedback, }, instruction=( "Review against the requested criteria. If the user did not provide " "factual values such as dates, URLs, or contacts, clear placeholders " "are acceptable: do not reject solely because they are not concrete " "and do not ask the writer to invent facts. Check that placeholders " "are clear and required fields or steps are complete." ), schema=review_schema, tools=[], ) decision = review["structured"] approved = decision["approved"] and not decision["feedback"] if approved or attempt == 3 or not decision["feedback"]: break previous_feedback = decision["feedback"] draft = await agent( {"draft": draft["text"], "feedback": previous_feedback}, instruction="Revise the draft using every required change.", tools=[], ) return { "draft": draft["text"], "approved": approved, "reviews": attempt, "remaining_feedback": decision["feedback"], } ``` On the third rejected review, return the latest reviewed draft and feedback; do not create a fourth, unreviewed revision. Adapt the role instructions and inputs to the current request rather than copying this shape as a fixed task. ## Review Discipline - Review only against the user's original request and its explicit quality criteria. Do not invent a broader deliverable. - When the user did not provide real names, dates, URLs, contacts, tools, or organization-specific facts, treat clear placeholders as acceptable. Do not reject solely for missing concrete values or ask the writer to invent them; check that the placeholders are clear and the required content is complete. - Return at most three material required changes per review. Do not reject for optional polish. - After a revision, first verify the previous required changes. Do not move the goalposts by adding unrelated requirements; add a new item only for a material regression introduced by the revision. - Approve once the required criteria and previous feedback are satisfied. ## Compilation Rules - Express the review cycle as an explicit bounded loop in one Dynamic Workflow. - Use separate workflow-local Agent instances for writer and reviewer. - Keep both roles tool-free unless the user's request clearly needs a capability already allowed by the registered Agent template. - Use model-native structured output for the approval decision. Do not parse a JSON-looking text response. - Read the branch fields from the Agent result's explicit `structured` object. - Pass task facts and feedback through Agent inputs. Do not rely on a role to remember facts that were never provided to it.