image-refine

Owns

Everything done to a picture after one exists — a targeted edit, a reworked prompt, an extension, an upscale — and the discipline that keeps an iteration from drifting into a different picture. It does not decide whether the result is good enough; that judgement belongs to a reader who did not make the change.

Phases: LOCATE → CLASSIFY → INVARIANTS → CHANGE → COMPARE.

Before starting

• Name a falsifiable correction objective before touching anything. Locate its region(s), or name the whole frame for a settled palette/light correction. An undefined aesthetic goal goes back to direction, not a speculative edit
• Write the invariants down. Everything that must not move is stated before the edit and restated in every iteration, because drift is cumulative and invisible one step at a time
• Keep the original. The starting image is an inputs entry in the new recipe, and it stays on disk until the result is accepted

• Size it before anything else, first match wins. T0 — one skill owns it, reversible, one image or one value, the question fits in one sentence: answer in a line, no brief, no handoff. T1 — a T0 condition fails: settle the brief first. T2 — two or more skills own parts of it: route it. T0 drops the paperwork, never the evidence. Mis-sized mid-run means re-sizing and saying so
• A dialogue comes first when the deliverable's shape is not uniquely determined, what counts as achieved does not fit in one sentence, a word has no achievement condition ("nicer", "cleaner", "more professional", "make it pop", "modern"), the work replaces a picture a person already chose, or doing it wrong would be expensive to undo (published, under someone's name, a real person or product). Looking at what exists is not executing
• Settle standard in that dialogue — what the image is judged against. Without one, every candidate is arguable and the loop has no exit. excludes may not be empty and execution waits on an empty open_questions (_image/SIZING.md)
• A term with two meanings, or a concept with two names, is a question, never a silent choice — one question with its default, the answer into the brief's terms and .agents/glossary.md, and the glossary's names only from then on (_image/SIZING.md § Terms)

• Retained generated candidates carry a recipe: engine, reported model (or unreported), prompt verbatim, excluded, size requested/on disk, inputs, output. Capture the request at invocation; persist for candidates shown, kept or passed onward, not immediate discards. References and text-only outputs need no invented generation fields. IRREPRODUCIBLE limits exact pixel regeneration, not reuse or editing the source (_image/RECIPE.md)

Decide first

Situation	How to proceed
Turning a complaint into something a model can act on	locate-then-change
Choosing how hard a change to make	edit-ladder — crop or scale, region edit, extend, re-prompt with invariants, back to the brief; take the lowest rung that can work
Picking the edit mode the generator understands	edit-modes — the taxonomy the backing skill keys off, and what each preserves
A transparent cutout is wanted	cutouts — chroma key, then local removal, then check the alpha
Checking what moved that should not have	imgfacts on the before and the after — an edit path can change dimensions or format without saying so
The change has failed twice the same way	Stop and hand back. A third attempt at the same rung is how a budget is spent proving nothing
A claim here would be expensive to get wrong	refute — put it to the engines that did not make it, asked to break it rather than to agree. Unrefuted is n engines finding nothing, never proof
The fix would change who or what the picture depicts	That is not a refinement. Hand it back

• Ties break by _image/VALUES.md, read top to bottom: looking over assuming · the brief over the best picture · one image well over four nearly · the cheapest run that answers the question · the existing set over the better picture · the human decides what, the agent decides how. Against all of them: a harness that is correct and avoided has failed — when the ceremony costs more than the decision, say so rather than performing it

Always / Never

• Always: one falsifiable correction objective per iteration. Coupled changes (remove + fill, both hands, several letters) may share a run; check every part
• Always: open the before and the after and say what moved that should not have
• Always: record each retained generative edit as its own recipe with source inputs; deterministic transforms inherit provenance and record the operation
• Always: get permission first when the edit would alter a person's appearance, a brand mark, or anything already published
• Never: describe an edit as applied without opening the result
• Never: carry approval over to a regenerated picture. It can solve the fault, but is a new candidate; IRREPRODUCIBLE and fresh review still apply
• Never: drop an invariant because the new result is nicer without it
• Never: upscale to hide a defect. It scales too

Verify with

Before and after are both opened, and the invariants are checked one by one against the pair (evidence: measured — each invariant is a thing that can be looked at in a named region). An invariant asserted rather than checked is drift that has not been noticed yet.

• Dimensions and format are read off the result, because an edit path can change either without saying so
• The chain is stated: how many iterations, what each changed, and what the next one would be for

• Grade every claim: measured names the measurement method or a located, repeatable visual observation, not aesthetic certainty. inspected is reasoned judgement where measurement cannot settle the decision; say why. Header inspection is not viewing pixels. asserted never supports completion: the prompt asked for 3:2, it does not report what came back
• The unit is the decision, not the batch. Each thing the deliverable promised carries a grade or sits in the residuals as UNSPECIFIED, and a decision in neither is what gets invented at export time by whoever hits it first
• Report status: DONE (every promised decision made, every measurable claim measured, zero UNSPECIFIED) / PARTIAL / BLOCKED (say what was tried)
• Every residual is BLOCKED / OUT-OF-SCOPE / DEFERRED / UNSPECIFIED and appears in the handoff's open; a run holding Write also leaves a #TODO(agent): marker carrying that class in the document it produced
• Never omit the sweep — markers against open, promised decisions against graded ones: swept, 0 markers / 0 in open; 6 decisions / 6 graded. While either pair disagrees the status is not DONE (_image/CONTRACT.md)

Done when

The fault was located before the change, the invariants held under inspection, each step has its own recipe naming its source, and the result was opened and compared rather than assumed.

• Say what the moment needs. Start: one line naming what will be made and what is excluded. Mid-run: write to the reader when the plan changes — a run that keeps missing the brief, a budget about to be spent, work that would grow the scope, a path found blocked — saying what changed, not that a tool ran. Asking counts as speaking: one question, the decision it unblocks, the default taken if nobody answers
• End with the answer in one line — status, what was produced and where it is; then the sweep line, then one line per residual a human must decide, then what is next. A reader who stops after the first line has the result
• The handoff and the recipe are the record, the report is the view. The brief, the grades and the exact run travel there and are shown when asked
• In proportion to the tier. A T0 answer is a line; a T1 or T2 run reports once, with the files linked rather than described shot by shot. Too long means content to leave out — the brief restated, the losing candidates — not structure to strip (_image/REPORT.md)
• Not bigger than it is. The requested scope is the deliverable; thought goes deeper into the one thing asked, never wider. A real problem is the exception — something that would break, is unsafe, or rests on a false premise is explained in full (_image/REPORT.md)