Redline grade
What this page is — the capability that grades a counterparty's proposed change against your own clause-library playbook, and tells you whether you are already authorised to accept it.
What it is for — so "can I just say yes to this?" is answered by your organisation's pre-approved fallback positions rather than by a reviewer's judgement on the day.
The problem it solves — reviewers either escalate every change or accept ones outside what the organisation allows, depending on who is reviewing that day.
Route: /org/papers/documents/<document>/ai → Negotiate → Redline grade ·
Permission: Use AI drafting/extraction/Q&A for documents. ·
Utility: papers_redline_analyzer · Cost: 450 credits estimated, 1,800 maximum.
1. What it is
Your clause library holds, for a given clause, an approved standard position and an ordered list of fallback positions — the concessions your organisation has pre-authorised, from the smallest give at index 0 to progressively larger ones.
Redline grade decides three things about the counterparty's proposal:
- Is it materially equivalent to your standard, or to one of those fallbacks — that is, the same or better for you?
- If not, how far beyond your most permissive fallback does it reach?
- What is the concrete counter to send back?
It reasons about the wording, not about labels: a proposal that reaches your fallback #1 position through completely different drafting still matches fallback #1.
Nothing is accepted or rejected on your behalf. within_playbook: true means a human is
pre-authorised to say yes, not that anyone has.
| Compares against | Answers | |
|---|---|---|
| Redline grade | Your clause library's standard and fallbacks | "Am I authorised to accept this?" |
| Shadow redline | Your current text | "What did they slip into this round?" |
| Version diff | The prior version | "What changed?" |
| Compromise draft | — | "What third position could close this?" |
Redline grade must be told which redline to grade. Its executor refuses without a
suggestion_id or suggestion_text, so the interface asks first rather than offering a Run button
that would return "provide suggestion_id or suggestion_text in input" on every press.
2. Why you would use it
Every organisation with a playbook has the same problem: the playbook is a document, and the person reviewing the redline at 5pm on a Friday has not read it recently.
- It turns a policy document into a decision. The fallbacks exist precisely so that concessions do not need escalating. Without something checking against them, they get escalated anyway.
- It removes the escalation that was never needed.
within_playbook: trueon a change your reviewer was about to send to legal is an afternoon saved, repeatedly. matched_fallback_indextells you what it costs. Knowing the proposal lands on fallback #2 and not #0 is the difference between a free yes and a considered one.suggested_counteris your next message. When it is out of playbook, you get the nearest authorised fallback to offer instead — so a rejection comes with a proposal.- It makes the playbook falsifiable. A clause whose every incoming proposal grades out-of-playbook is telling you your standard is out of step with the market.
3. What you provide
The counterparty's proposed change — required, by one of two routes.
| Route | You give it | Use when |
|---|---|---|
| Pick an existing redline | A suggestion or redline comment already on the document | The change came through the platform. Prefer this |
| Paste the proposed text | The wording yourself, optionally naming the block it targets | The change arrived by email or on a call |
Picking an existing suggestion also carries the comment's block reference, which is what resolves the targeted block to its library clause and its fallback positions.
Graded from pasted text alone there is no block reference, so the model is told "no library standard for this block" and grades against general market practice instead. You still get a grade. You do not get your playbook applied to it — which is the entire point of the capability.
4. What it reads automatically
This capability reads more of your configuration than any other in the module.
| Read | From | Used for |
|---|---|---|
| Document text | The document | Surrounding context |
| Title & family — e.g. "MSA" | The document | Framing |
| Parties | The document | Whose exposure moves |
| Target clause body | Your clause library | Your approved standard position for that clause |
| Clause risk level | Your clause library | The library's risk rating for it |
| Fallback positions | Your clause library | Your ordered, pre-authorised concessions |
The bottom three rows are what it grades against. Without them there is no playbook to be inside of.
5. What you get back
| Field | Type | Values | Means |
|---|---|---|---|
within_playbook | boolean | — | true only when the proposal is materially equivalent to your standard or a fallback — same or better for you |
matched_fallback_index | number | 0-based, or -1 | The fallback it best corresponds to. -1 means either no match at all, or a match to your standard position |
deviation_severity | enum | high, medium, low, none | How far beyond your most permissive authorised fallback it goes. none = within playbook |
rationale | string | — | Why, citing the concrete differences between the proposal and your standard or fallback wording |
suggested_counter | string | — | The nearest authorised fallback when one is close; otherwise a redline pulling the proposal back inside the playbook |
matched_fallback_index: -1 is ambiguous on its ownIt means no fallback matched — which happens both when the proposal is out of playbook and when it simply matches your standard position, needing no fallback at all. Those are opposite outcomes.
Read it with within_playbook: true with -1 is the best possible result (they accepted your
standard); false with -1 is the worst (nothing authorised covers this).
6. Worked example
The counterparty comments on the liability clause of an MSA, proposing a cap.
Input: the existing counterparty suggestion on the Liability clause is selected.
Result:
within_playbook:
falsematched_fallback_index:-1deviation_severity:highsuggested_counter: "Offer fallback 0: cap at 12 months' fees but carve out confidentiality and IP breaches."
How to read it. within_playbook: false with -1 is the bad combination from §5 — nothing in the
library authorises this. high says it reaches well beyond even the most permissive fallback.
What the reviewer does. They do not escalate, because suggested_counter already contains the
answer: offer fallback 0, which is pre-authorised. The reply goes back the same afternoon proposing a
12-month cap with confidentiality and IP carved out — a position legal approved months ago.
Had the same proposal come back within_playbook: true with matched_fallback_index: 2, the
reviewer could have accepted it outright, while knowing it consumed the second of three authorised
concessions on that clause.
7. Running it
- Open the document in Orbit Papers and go to the clause under negotiation.
- Open the AI Assistant drawer, or go to the document's AI workspace.
- Choose Redline grade under Negotiate.
- Give it the change — pick an existing suggestion or redline comment (preferred), or paste the proposed text.
- The grade and suggested counter appear in a result tab and are saved to the document.
Grade each substantive incoming redline before responding. Nothing is accepted; the decision to concede stays with you.
Available for auto-run from the type's AI Config tab on the on_round event, where it is fed the
newest open redline automatically — on a round event that is precisely the change the counterparty
just sent back. See AI configuration.
8. The admin contract
| Must be true | Where | What happens if it is not |
|---|---|---|
| Your role holds Use AI drafting/extraction/Q&A for documents. | Role editor | The AI Assistant button does not appear |
The papers_redline_analyzer utility is active | Orbit AI Flow → utilities | "This utility is currently disabled" |
| The utility is enabled for your organisation | /org/ai-utilities | Absent from Negotiate, with no error |
papers.ai_monthly_credit_cap not yet reached | System Config | "monthly AI credit cap reached: n of n credits used this month" |
| The clause has an approved standard body | Clause library | There is no baseline, and it grades against general market practice |
| The clause has ordered fallback positions | Clause library | Every concession reads as out-of-playbook — the single most common cause of a wrong grade |
| Redlines arrive as suggestions on the document | Redlines and rounds | Only the weaker pasted-text path is available (§3) |
If a clause has no fallbacks defined, every concession grades as a deviation, and the capability becomes a machine for rejecting things you would happily have accepted. Keep each target clause's standard body and its ordered fallbacks current — they are the specification this measures against.
For a confidential document, auto-run is default-denied — a platform administrator must set
papers.ai_confidential_cloud to the literal allow, and the block appears only in the server log.
A manual press still works, and where a local model key is configured the run is forced on-prem and
audited on the timeline as ai_local_routed.
9. Don't confuse this with…
| Clause library | Where the standard and fallbacks are defined. This measures against them |
| Shadow redline | Sweeps a whole round for hidden liabilities. This grades one named change |
| Compromise draft | Invents a bridging position. This checks against positions you already approved |
| Version diff | Reports every meaningful change. This judges one |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| "provide suggestion_id or suggestion_text in input" | It was run without being told which redline to grade (§1) |
| Everything grades out-of-playbook | The clause has no fallback positions defined in the library (§8) |
matched_fallback_index: -1 but within_playbook: true | It matched your standard position, needing no fallback. The best outcome (§5) |
| The grade ignores our playbook entirely | It was run from pasted text, so there is no block reference to resolve the library clause (§3) |
| The grade seems generous | Check which fallback matched — a match to your weakest authorised position is still "within playbook" |
| A clause we changed last month grades oddly | The library holds the old standard. Update the clause body, not the grade |
| The capability is missing from Negotiate | Role lacks Use AI drafting/extraction/Q&A for documents., or the utility is off for the organisation (§8). The document type does not gate it — AI Config controls auto-run only |