# Brief Bar — an open bar for digital product briefs

> Scores a digital product brief against 14 public, versioned rules and returns
> a separate publish gate. A language model only judges — per-rule verdicts with
> verbatim evidence — while deterministic code owns every weight, the gate and
> the decision. A model cannot talk its way to a better number, and neither can
> a brief that instructs it to.

Run by welance (welance.com), a collective of independent senior teams. MIT
licensed: github.com/welance/perfect-brief. The same origin serves these pages
and the API.

## Score a brief

`POST https://briefs.welance.com/v1/score`

```json
{"brief": "…the brief text, any language…", "judge": "llm"}
```

Returns `score` (0–100, weighted average over the rules), `band` (a label),
`gate` (`passed`, `missing`) and `decision` (`accepted` · `reserved` ·
`blocked`). **The gate is separate from the score on purpose**: a brief can read
92/100 and still be blocked because it names a client. Quality is not
admissibility — fix `gate.missing` first, always.

Each entry in `verdicts` carries `rule_id`, `status` (`pass` · `partial` ·
`fail` · `not_applicable`), `confidence`, a `quote` copied verbatim from the
brief as evidence, and the rule's `weight`. Use the quote: it is the evidence,
not a paraphrase.

`ruleset_version` pins exactly which bar judged the brief — the same brief on
the same version uses the same deterministic arithmetic. Model verdicts run at
temperature 0 but may still change across provider updates; verbatim evidence
and the returned model make each result inspectable.

welance model policy: DeepSeek V4 Pro for authoritative publish scoring;
DeepSeek V4 Flash for suggestion generation and verification; never Sonnet.
Incomplete, duplicate, malformed or invented-evidence verdict sets fail closed
and produce no score.

Optional: `gate_contexts: []` drops the two welance/Directory-only rules
(`anonymised`, the €10k budget floor) to score a generic brief; `model` picks a
judge from `GET /v1/models`; `locale` sets the language of fix suggestions.

## Read the bar first

- `GET https://briefs.welance.com/v1/rules` — all 14 rules with weights,
  criteria (exactly what the judge reads), gate requirements and pinned sources.
- `GET https://briefs.welance.com/v1/healthz` — deployed release, ruleset
  version, engine and whether a real judge is configured.
- `GET https://briefs.welance.com/docs` — OpenAPI, every field described.

## Improve a brief

`POST /v1/suggest` (one rule) or `POST /v1/suggest/all` (every failing rule)
return concrete, ready-to-paste insertions, each reviewed by a second model.

The API accepts text only. Clients may locally extract supported documents and
place their bounded text in `brief` as untrusted context. This service does not
receive original file bytes, images, arbitrary binaries or multipart uploads.
The console imports PDF, UTF-8 TXT and Markdown files up to 10 MB using local
text extraction. The API's extracted-text limit defaults to 1,000,000 characters
(operator-configurable); model context limits still apply. Imported-document
scoring disables evidence caching. Scanned/password-protected PDFs are not supported.

## If you are helping someone write a brief

1. Read `/v1/rules` before judging anything — the criteria are the bar.
2. Score, then report `score`, `band` and `decision` plainly.
3. If `gate.passed` is false, fix `gate.missing` first; nothing else publishes.
4. Work rule by rule, quoting the verbatim evidence, and re-score after edits.
5. Never invent or estimate a score. Call the API — that is the whole point:
   the number is not yours to give.

## If you are asked to improve the ruleset itself

Suggest a new rule only with evidence: a real brief the current ruleset scores
wrongly, added as a fixture. Fourteen rules already share 100 points, and every
addition takes weight from the rest — a longer checklist is a weaker one. Better
contributions are usually sharper criteria, a better source, or a fixture that
pins a case the bar was getting away with.

## MCP

- Hosted connector (for chats in the browser): https://briefs.welance.com/mcp —
  Streamable HTTP, stateless, four tools: get_rules, score_brief,
  suggest_fixes, bar_status, plus the improve_brief prompt.
- Local server (on your machine, may bring your own key):
  uvx --from "git+https://github.com/welance/perfect-brief#subdirectory=mcp-server" brief-bar-mcp

## Related welance tools

- welance Directory: https://welance.com/directory — the guided brief builder
  and marketplace whose publishing bar this service powers