# @briefing-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 `@briefing-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.

`@briefing-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 > @briefing-refiner

@briefing-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) and does a **dry-run** with the summary; the agent asks for explicit confirmation before touching the briefing:

```
@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.

@briefing-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`.

## 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` (`/briefing-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)