Review

---
name: review
description: 'FluencyLoop Stage 4. Assemble the reviewer-facing PR view from a feature''s sessions — a feature is a branch, so it assembles itself from git. Use when preparing a PR description, reviewing a FluencyLoop feature, or when the user says "fluencyloop review", "assemble the PR view", or "summarise this feature for review".'
---

# /fluencyloop:review — Stage 4, assemble the PR view

A **feature is a branch**, so the review view assembles itself: no manual linking. You turn
the feature's sessions into a summary a reviewer can read to get fluent fast.

## Bundled CLI (Claude Code)

Before invoking a deterministic command, use this plugin's bundled launcher:
`"${CLAUDE_PLUGIN_ROOT}/bin/fluencyloop" <arguments>`. Every `fluencyloop …` command below
means that exact Bash-tool command; it is never a chat instruction or a globally installed
command.

Do not hand-scaffold `.fluencyloop/`, `.claude/skills/`, designs, sessions, state, or helper
scripts. The bundled CLI creates the deterministic files and returns their paths.

## Local site — open once

Before the first user-visible response, invoke
`"${CLAUDE_PLUGIN_ROOT}/bin/fluencyloop" site --ensure --open-once --json`. This ensures the
reader for every workflow entry, but opens a browser tab only once while that managed reader is
alive. If it reports `running: true` and no earlier assistant message in this session starts with
`FluencyLoop site:`, say `FluencyLoop site: <url> (opened in browser).` once, using its returned
URL. Do not mention an unavailable site or repeat the announcement.

## Generated prose — ASD-STE100

Write generated user-facing technical prose in ASD-STE100 style: use short, direct sentences,
active voice, one main action per sentence, and stable, unambiguous terms. Preserve product names,
code identifiers, CLI commands, field names, and exact recorded values. Do not claim formal
ASD-STE100 compliance: that requires checking the official controlled dictionary and rules.

## Question delivery — preserve the pause

For a real answer, choice, or confirmation, use **`AskUserQuestion` in Claude Code**. Codex has
no equivalent question-form tool, so ask a concise standalone question in chat and stop; do not
create a PR or persist a preference until the developer answers.

## 1. Gather the raw material

**Read `.fluencyloop/state.json` first** if it exists — it is the loop's source of truth for the
active feature (`feature` slug, `branch`, `base_ref`), so you don't re-derive them from git. Use
its `base_ref` as the diff base (`--base`) rather than guessing the default branch.

From the feature branch (or pass `--slug`):

```bash
fluencyloop review --json                    # paths, commit range, session list
fluencyloop review --base "<base_ref>"       # scope the diff to the recorded base
```

The `--json` form gives `feature`, `range`, `commits`, and session declarations from the feature
store. The plain form inlines every session's decisions under the feature title.

## 2. Render the reviewer view

Produce a concise, reviewer-facing summary:

- **One-line feature intent** (from the feature declaration's `intent` field in the store).
- **Decisions that matter**, grouped by session — each as *chose X over Y because Z*, with
  its `where:` code anchor. Lead with the decisions carrying `trust: ⚠` — those are where a
  reviewer should look hardest.
- **Constitution check:** scan each decision's `constitution:` field against the project's
  principles — read `docs/fluencyloop/constitution.md`, and **if it's a pointer** (`Source of
  truth:` naming another file, e.g. `.specify/memory/constitution.md`), read *that* for the
  real principles. **Flag** any decision that appears to conflict, or any principle-relevant
  decision that was never checked. Flag as a surfaced note — never a blocker.
- **Design shape:** summarize the relevant session, decision, and architectural records; do not
  create or link a generated `design.md`.
- **Un-journaled drift:** run `fluencyloop check --json` and read `unjournaled_commits`. If it's > 0, warn that N commit(s) landed since the
  last journaled session — the reviewer is looking at code the journal doesn't explain, so nudge
  the author to journal it or run backfill. Surface it as a note; never block.

## 3. Output — create the PR, don't hand over text to paste

The point is to remove friction, so **create a prepopulated PR** rather than leaving the user
to copy-paste into GitHub.

1. Make sure the branch is pushed (`git push -u origin <branch>` if it has no upstream).
2. If `gh` is available (`command -v gh`), create the PR with the assembled view as the body:

   ```bash
   gh pr create --title "<feature intent>" --body-file <tmpfile>   # base defaults to main
   ```

   Confirm the title/base with the user first; show them the body you're about to use. On
   success, give them the PR URL.
3. If `gh` is **not** available, still deliver — and make a **one-time** setup offer, because `gh`
   is what lets FluencyLoop open the PR for you. First hand over the reviewer view **rendered**, and
   a **prepopulated compare URL** that opens a ready-to-file PR in the browser (no `gh`, any OS):
   `https://github.com/<owner>/<repo>/compare/<base>...<branch>?expand=1&title=<t>&body=<url-encoded>`
   (mind the URL length limit; fall back to the pasteable body if it's too long). Then check
   `~/.fluencyloop/preferences.md` for a settled `gh-setup` choice:
   - **Not settled yet** — offer **once** using the delivery rule above, selling it: *"Want me to set up
     `gh` so I open your PRs (and file your plan's issues) automatically from here on? One-time —
     I won't ask again."* Options **Yes, set it up** *(recommended, list first)* / **Not now**.
     Record `gh-setup: done` / `gh-setup: declined` to `preferences.md`; never ask again. On **yes**,
     install `gh` the way that fits their OS — don't work from a hardcoded package-manager list; the
     canonical installer for every platform is <https://cli.github.com> — then `gh auth login` and
     create the PR (step 2).
   - **Already `declined`** — don't re-offer; the compare URL above is the path.

Put any external link in the PR's first comment, not the body. Do **not** merge the PR unless
explicitly asked.

## Rules

- **Surface, don't gate.** Flag unverified trust and constitution conflicts; never block.
- **Truthful assembly.** Summarise what the sessions actually say; if a decision has no
  journaled `why`, say it's undocumented rather than inventing one — or suggest
  **`/fluencyloop:backfill`**.