document-brief · diff
v1.0.0 to v1.0.1
11 added, 1 removed. Audit A to A.
---
name: document-brief
description: Index a document or folder and answer questions about it with quotes from the source. Use when the user points at a PDF, contract, spec, report, or folder of files and asks what it says, what changed, or what they should worry about.
license: MIT
- version: 1.0.0
+ version: 1.0.1
metadata:
gaia:
security_tier: community
tools_required:
- index_document
- index_directory
- list_indexed_documents
- query_documents
- summarize_document
- rag_status
+ - read_file
provenance:
source: starter-pack
---
# Document Brief
Reading a long document for someone is not summarization — it is answering the
question they actually have, with the sentence that proves it.
+
+ ## A few documents? Read them in full
+
+ To review, compare or reconcile a handful of documents, `read_file` each one in
+ full instead of indexing it — it returns Word, PDF and Excel text; follow
+ `next_offset` until it is null — and work from the whole text. A retrieved
+ snippet only holds what a query asked for, and a date or amount that differs
+ between two documents is exactly what no query asks for. The procedure below is
+ for a large collection or a single lookup.
## Procedure
1. **Check what is already indexed** with `list_indexed_documents()`. If the
file the user named is already there, skip straight to step 3 — re-indexing
is slow and buys nothing.
2. **Index it.** `index_document(file_path)` for one file, or
`index_directory(directory_path, recursive=True)` for a folder. If indexing
fails, run `rag_status()` and report what it says — do not answer from the
filename.
3. **Answer with `query_documents(query)`.** Ask one focused question at a time;
a compound question retrieves worse than two simple ones.
4. **Quote the source.** Every claim in your answer carries the sentence or
figure it came from. If retrieval returns nothing relevant, say "the document
does not appear to cover that" — never fill the gap from general knowledge.
5. **Offer the brief.** For a document the user has not read at all, lead with
`summarize_document(file_path)` and then invite specific questions.
## Standing brief format
When the user asks for "a brief" rather than a specific question:
- **What it is** — one line.
- **What matters** — the 3–5 points that would change a decision.
- **What to watch** — obligations, deadlines, numbers that move.
- **Open questions** — what the document leaves unresolved.
## Fork this
Replace the brief format with your domain's checklist and it becomes a reviewer:
for a contract, ask for termination, liability, auto-renewal, and payment terms
by name in step 3 so they are never skipped.