# @refiner — Review and refine a briefing before the PRD

> **Who this is for:** anyone who wants to review an existing briefing or explore a visual direction before creating one.
> **Reading time:** 5 min.
> **What you'll know after:**
> - What `@refiner` does and where it fits in the flow.
> - How the round-based refinement loop works (audit → browser review → apply).
> - How the `review.html` surface actually saves (local autosave + 3 routes to return the JSON).

## What it is for

Between the generated briefing and the PRD there is a step that usually gets skipped: **reviewing the briefing with a critical eye**. Ambiguities, redundancies, missing decisions, vague risks, and implementation-impact gaps go straight to `@product` and become debt in the PRD.

`@refiner` fills that step as a **loop of rounds**: it audits the briefing and records **structured findings** (category, severity, and whether they block the PRD); the CLI renders the deterministic review surface (`aioson briefing:review`); you decide each finding and edit each section in the browser; the structured feedback comes back and is applied (`aioson briefing:apply-feedback`) — and the cycle repeats until nothing blocks the PRD.

It is the complement of [`@briefing`](../../pt/4-agentes/briefing.md): one generates, the other refines.

## When to invoke

- You already have a briefing in `.aioson/briefings/{slug}/briefings.md` and want to review it before the PRD.
- The briefing is `draft`, or `approved` but still **without a generated PRD** (`prd_generated: null`).
- You want to record comments, decide findings, request per-section changes, or flag blockers before moving on to `@product`.
- You want to **see the solution** before the PRD (prototype mode) and, optionally, define the visual identity from your reference images.
- No Briefing exists yet, but you want to test a redesign, screenshot references, one variant, or a multi-model arena.

## When NOT to invoke

- No briefing exists and the request is non-visual framing — go to [`@briefing`](../../pt/4-agentes/briefing.md).
- The briefing already produced a PRD (`prd_generated` filled) — refining would require a new PRD/enrichment route, outside this agent.
- The idea changed so much that regenerating from scratch is better — go back to `@briefing`.

## When no Briefing exists: visual exploration

The Refiner offers to create the Briefing first, start an exploration, or continue an existing one. Exploration confirms the target, chooses `single`, `sequential`, or `arena`, evaluates screenshot coverage, and asks whether a `targeted` or `full` scan should complement the current-system evidence.

Variants live under `.aioson/explorations/{slug}/`, each with exclusive model ownership, prototype, and report. Comparison may be blind, supports region comments, and preserves reusable “killer prompts” from every attempt. A selected direction enters the canonical flow only when `exploration:promote` creates `plans/{briefing-slug}/visual-exploration.md`; `@briefing` then creates the Briefing and the Refiner consolidates the feature-owned prototype.

See [Visual exploration and multi-model arena](../3-recipes/visual-exploration-arena.md).

## The canonical refinement loop

```
audit (agent) → review.html (CLI) → you decide in the browser
      ↑                                        ↓
regenerate the review  ←  apply confirmed feedback (CLI)
(while blockers or text changes remain)
```

Each round is numbered (`round`) and archives the consumed feedback (`refinement-feedback.applied-round{N}.json`), so "`refinement-feedback.json` exists" = "there is pending feedback" — a deterministic signal.

### 1. Generate the review

The agent audits the briefing and writes the findings to `refinement-findings.json`; the CLI validates and renders:

```
You > @refiner

@refiner > Refinable briefing found: marketplace-v1 (draft).

                    Auditing... 10 findings (3 ambiguities, 2 gaps,
                    1 blocking: commission model undefined).

                    aioson briefing:review . --slug=marketplace-v1  ✓ (round 1)

                    Open .aioson/briefings/marketplace-v1/review.html
                    in a REAL BROWSER (double-click) — editor previews
                    are sandboxed and block saving/downloading.
```

### 2. Apply pending feedback

The CLI validates (schema, slug, source hash). If you saved the page with no note and the recommended options, saving was the confirmation, and the round is applied with no other question, unless the text would go beyond your decisions. Any other round gets a **dry-run** with the summary, and the agent asks for explicit confirmation before touching the briefing:

```
@refiner > Pending feedback on marketplace-v1 (round 1):
                    - 4 sections changed, 1 blocked
                    - findings: 6 accepted, 2 rejected, 1 deferred, 1 pending (blocking)

                    Apply the confirmed changes? The pending blocking
                    finding keeps the PRD blocked.
You > Yes.

@refiner > aioson briefing:apply-feedback --confirm  ✓
                    Applied; briefing reverted from approved to draft.
                    Blocker remains → regenerating the review (round 2)...
```

If you decline, `briefings.md` stays intact and the skipped changes are recorded in the report. When no blocker remains: `aioson briefing:approve . --slug={slug}` → `@product`.

Before folding notes in, `@refiner` reads the round through `aioson briefing:feedback . --slug={slug}`: the lean view with every finding, comment, decision and blocking item, plus the text of only the sections a note or a status change touched. The exported JSON carries the whole briefing twice (original and current text of every section); the lean view is about 5% of the file, and the agent edits only the named sections.

## The review surface (review.html)

Rendered by the CLI (`aioson briefing:review`) — static, local, self-contained, and in your language:

- plain-text editable sections + per-section status (`unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`) and notes;
- **audit findings rendered per section**, each with its own decision (`pending`/`accepted`/`rejected`/`deferred`) and note — with working category filters;
- a panel showing what changed, what blocks the PRD, and how many findings are still pending;
- **local autosave**: every edit is saved in the browser (localStorage) and restored on reopen — closing the tab loses nothing;
- **3 routes to return the JSON**: *Save to file* (File System Access, with an automatic fallback to download when the context is sandboxed), *Download JSON* (and move it over `refinement-feedback.json`), or *Copy JSON and paste it in the chat* — the lowest-friction route.

> **Why JSON and not the edited HTML?** The agent never treats the edited DOM/HTML as canonical feedback — only the structured `refinement-feedback.json` (schema v1.1, validated by source hash). That prevents applying inferred changes and keeps the process auditable.

> **Important:** open `review.html` in a real browser (double-click). Embedded editor previews run in a sandbox and block the file picker and downloads.

## Prototype mode and visual identity (optional)

For rich-surface briefings (workspaces, boards, CRM/Kanban, dashboards, repeated-use CRUD), the agent recommends — without blocking — generating a clickable prototype before the PRD. This is the moment (or already during the review, via a non-blocking finding) where the **visual identity** comes in:

- you drop reference images into `references/identity/` (brand: color, typography, mood) and `references/structure/` (a board, a table, a screen);
- the `reference-identity-extract` skill reads the images **once** and writes `identity.md` (tokens + per-component structure notes);
- the `interface-design` engine **applies** `identity.md` to everything downstream (prototype and build) — with no images, it runs intent-first.

The prototype is mock-only and never becomes canonical feedback.

## Outputs on disk

| File | What it contains |
|---|---|
| `.aioson/briefings/{slug}/refinement-findings.json` | The agent's audit findings (CLI input) |
| `.aioson/briefings/{slug}/review.html` | Review surface rendered by the CLI |
| `.aioson/briefings/{slug}/refinement-feedback.json` | Structured v1.1 feedback (the only source that gets applied) |
| `.aioson/briefings/{slug}/refinement-report.md` | Round report: applied, skipped, blocked, findings |
| `.aioson/briefings/{slug}/refinement-*.applied-round{N}.json` | Per-round archive (consumed feedback and findings) |
| `.aioson/briefings/{slug}/briefings.md` | Updated **only** after confirmation |
| `.aioson/briefings/config.md` | Updated briefing index/registry |
| `.aioson/explorations/{slug}/` | Intake, references, variants, comparison, and reports for a non-canonical exploration |
| `plans/{briefing-slug}/visual-exploration.md` | Fingerprinted promoted source for `@briefing` |

## How it reads your project

1. `.aioson/config.md`
2. `.aioson/context/project.context.md`
3. `.aioson/briefings/config.md` — resolves the refinable slug; when absent, selects Briefing or visual exploration.
4. `.aioson/briefings/{slug}/briefings.md` — read before writing any review artifact.

## Hard constraints

- Never creates or edits `prd*.md`.
- Never approves a briefing automatically.
- Never routes to `@product` while blocking items remain (including a pending blocking finding).
- Never treats edited HTML/DOM as canonical feedback — only the structured JSON.
- Never hand-writes `review.html` or applies feedback manually while the CLI commands exist — the done-gate (`verify:artifact --kind=review`) rejects hand-rolled surfaces.
- Never discards mandatory briefing sections.

## `--help` option

An activation with `--help` (`/refiner --help`) prints a quick summary — what it does, when to use it, typical call, what it produces, next agent — localized in your language, and stops without executing anything. Source: `.aioson/docs/agent-help.md`.

## Typical handoff

- **Comes from:** [`@briefing`](../../pt/4-agentes/briefing.md) (briefing generated) or you, resuming a review.
- **Goes to:** after applying the changes with no blockers → `aioson briefing:approve . --slug={slug}` → [`@product`](../../pt/4-agentes/product.md); for rich surfaces, prototype mode first. If a blocker remains, the next round of the loop resolves it — never manual editing.

## Next step

- Generate the briefing before refining → [@briefing (PT card)](../../pt/4-agentes/briefing.md)
- Full flow up to the PRD → [From idea to PRD via briefing](../3-recipes/from-idea-to-prd-via-briefing.md)
- Terms like "gap" and "PRD" → [Glossary](../1-understand/glossary.md)