Refinement turns specific feedback or newly gathered answers into an improved artifact. It is the implementation step in an evaluation-to-improvement workflow, not a substitute for evaluation: self-reflection identifies weaknesses, while inversion raises questions whose answers can guide revision. Skip refinement when the original already meets requirements or the feedback is too vague to act on. section 4.8
Use a repeatable revision sequence:
- Start with the existing content and evaluate it against its intended use. Record concrete omissions, risks, or questions rather than requesting a generic improvement. section 4.8 section 4.8.1
- Resolve questions that require outside knowledge before revising. For a risky refactor, establish downstream dependencies, implicit contracts, and viable rollback mechanisms. section 5.3.3
- Prompt for the revised artifact using the feedback or answers as explicit inputs. Specify what to preserve, what to add, and the required output format. section 4.8.1 section 5.3.3
Refine endpoint documentation
An initial description—“POST /orders. Creates a new order. Send order data in the request body. Returns the created order.”—does not tell developers enough to integrate. Evaluation identifies missing request fields and validation rules, authentication, status codes, error responses, and examples. A refinement prompt then asks for a concise, developer-focused revision addressing those identified gaps. The revision target is explicit; the prompt does not supply the missing API facts. section 4.8.1
Refine a legacy refactor plan
Before planning a legacy-module refactor, inversion asks about consumers of billing_events, undocumented service behavior, and rollback options. Once assessment answers establish the dependencies and constraints, a refinement template assigns a staff-engineer role and requests a concise plan with phases, a checkpoint, and rollout and rollback logic. Goal, timeline, team capacity, and risk tolerance remain visible inputs, so the plan rests on known conditions rather than guesses. section 5.3.3 section 5.3
The key test is whether each revision answers a specific finding. If critique has not produced actionable information, gather it first; otherwise, a polished rewrite can leave the original risk intact. section 4.8 section 5.3.1
