Retention advice
What this page is — the capability that works out how long a document must legally be kept, and proposes a concrete keep-until date with the statute it relied on.
What it is for — so retention is a defensible decision with a cited basis, rather than a default of "keep everything forever" or "delete after seven years because someone said so".
The problem it solves — retention periods are guessed, so records are either kept forever or destroyed before the law allows.
Route: /org/papers/documents/<document>/ai → Understand → Retention advice ·
Permission: Use AI drafting/extraction/Q&A for documents. ·
Utility: papers_retention_advisor · Cost: 450 credits estimated, 1,800 maximum.
1. What it is
The advisor finds the governing records-retention obligation for the document's class and jurisdiction, then proposes a date. Two rules govern how it gets there, and both are worth knowing because they are what make the answer defensible:
It anchors on the most defensible trigger it can find, in this order:
| Priority | Trigger | Why it ranks here |
|---|---|---|
| 1 | Expiry | The obligation clock usually starts when the relationship ends |
| 2 | Execution | When there is no expiry, the date it was signed |
| 3 | Creation | Last resort — when neither of the above exists on the document |
Where regimes overlap, it keeps the longest. A document caught by both the Indian Companies Act (8 years for books and records) and a Limitation Act contract-claim window (3 years) is advised at 8 years, and the rationale names the shorter regime it set aside. It knows the common Indian regimes — Companies Act, Income-tax Act (6 assessment years), GST Act (72 months) — as well as generic limitation windows.
The advisor recommends. It does not set a retention date, does not apply a legal hold, and does not dispose of anything. A person applies the result, or does not. This is the one capability where that separation is a compliance property rather than a convenience.
| Does | |
|---|---|
| Retention advice | Recommends a keep-until date, with the statute cited |
| File plans & series | Where retention rules are actually configured and applied at scale |
| Compliance & policy check | Checks the document's clauses against your policy — not its retention |
If you find yourself running this on every document of the same type, the answer belongs in a retention schedule on a file plan, not in a per-document AI run.
2. Why you would use it
Retention is the area where doing nothing feels safe and is not. Keeping everything forever is a data-protection liability and a discovery cost; deleting on a guessed schedule is worse.
- It produces an auditable basis, not a number.
basis[]names the statute, the jurisdiction and how confident the citation is. When a regulator or an auditor asks why seven years, there is an answer on the document. - It handles the overlap problem. Most documents are caught by more than one regime, and the interaction is exactly where non-specialists get it wrong. Keeping the longest and naming the others is the correct conservative answer.
- It picks the right trigger. "Seven years from when?" is the question that quietly makes retention policies wrong. Anchoring on expiry over execution over creation is a defensible rule, applied consistently.
- It surfaces legal holds before disposal. If a hold is active,
legal_hold_notesays so — the one output that must never be overridden.
3. What you provide
One optional input.
| Input | Required | Notes |
|---|---|---|
| Jurisdiction override | Optional | The jurisdiction whose retention rules should govern. Leave blank and it is inferred |
Leave it blank and the advisor infers jurisdiction from the governing-law clause, the addresses on the document, and the currency.
Set it when the document is silent about jurisdiction, or when your filing obligation follows a different place from the document's governing law — a contract governed by English law held by an Indian entity is filed under Indian rules.
Accepted at either granularity:
| Example | Level |
|---|---|
India | Country |
Delaware, USA | State within a country |
4. What it reads automatically
| Read from the document | Used for |
|---|---|
| Document text — the full rendered body | Identifying what kind of record it is |
| Title & family | The document class it must find a rule for |
| Parties | Which entity's filing obligation applies |
| Key field values | Filled schema fields |
| Jurisdiction hints — governing law, addresses, currency | Inferring jurisdiction, when the override is blank |
| Document dates — creation, execution, expiry | Picking the trigger (§1) |
| Retention state — existing retention date, active legal hold | Whether a hold blocks disposal |
5. What you get back
| Field | Type | Values | Means |
|---|---|---|---|
proposed_retention_until | string | YYYY-MM-DD | The keep-until date: trigger date plus the period |
retention_years | number | — | The number of years applied |
rationale | string | 2–4 sentences | Which trigger, which period, and why. Names the regimes it set aside |
basis[] | array | — | One entry per rule relied on |
basis[].rule | string | — | The statute or recognised practice |
basis[].jurisdiction | string | — | Where that rule applies |
basis[].source_confidence | enum | high, medium, low | low means it is inferring a period rather than citing a known one |
legal_hold_note | string | blank when no hold | Present only when an active legal hold exists — states disposal is blocked regardless of this advice |
disclaimer | string | — | That this is AI-generated guidance, not legal advice |
Read source_confidence before acting. A low entry is the advisor telling you it reasoned to a
period rather than citing one — exactly the case a records owner should check.
6. Worked example
A records owner needs a keep-until date for a vendor agreement executed in India in March 2025.
Input: jurisdiction override left blank — the governing-law clause names India.
Result:
proposed_retention_until:
2033-03-31retention_years:8basis: Companies Act 2013 · India ·highrationale: "Anchored on FY-end after execution; 8-year books-and-records period kept over the 3-year Limitation Act window." legal_hold_note: (blank)
What the owner does with it. Three things are checkable in under a minute: the trigger (FY-end
after execution, not the execution date itself — an Indian books-and-records convention), the period
(8 years, high confidence, a real statute), and the discarded alternative (the 3-year window,
named so the reader can disagree). They set the retention date on the document by hand.
Had legal_hold_note carried text, that step would have stopped there: a hold blocks disposal
whatever the advice says.
7. Running it
- Open the document in Orbit Papers.
- Open the AI Assistant drawer, or go to the document's AI workspace.
- Choose Retention advice under Understand.
- Optionally set a jurisdiction override; otherwise leave it inferred.
- The recommendation appears in the result tab, for a person to review and apply.
Nothing is written to the document. Applying the advice means setting the retention date yourself — see File plans & series for where retention actually lives.
Retention advice can be set to auto-run from the type's AI Config tab. on_finalize is the only
sensible event: retention is a property of a finished record, and running it on a draft anchors on a
creation date that will not be the trigger. 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_retention_advisor utility is active | Orbit AI Flow → utilities | "This utility is currently disabled" |
| The utility is enabled for your organisation | /org/ai-utilities | Absent from Understand, 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 document carries execution or expiry dates | The document | It falls back to the creation date — a weaker trigger, and the rationale says so |
| Someone owns applying the advice | Your process | The advice sits in a result tab and nothing is retained or disposed. This capability has no automatic effect at all |
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…
| File plans & series | Where retention schedules are configured and applied to many records. This advises on one |
| Retention & holds | Where a hold is actually placed and disposal blocked. This only reports that one exists |
| Compliance & policy check | Audits the clauses against policy, not the retention period |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| The retention date was not set on the document | It never is. The advisor recommends only — a person applies it (§7) |
source_confidence: low on every entry | The document's class or jurisdiction is unclear, so the advisor is inferring. Set the jurisdiction override (§3) |
| The jurisdiction is wrong | It was inferred from governing law. Your filing obligation may differ — set the override |
| The period looks too long | Overlapping regimes: it keeps the longest and names the others in rationale. Read which ones it set aside |
| The date is anchored on creation, not expiry | The document carries no expiry or execution date, so it fell to the last-resort trigger (§1) |
legal_hold_note has text | An active legal hold exists. Disposal is blocked regardless of the advice — do not proceed |
| The capability is missing from Understand | 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 |