Document Extraction is the process by which Catalio reads an uploaded Artifact and either compares it against an Application’s connected repositories or enriches an Initiative’s PRD. Application comparison produces Change Proposals directly; Initiative enrichment only produces proposals after a separate Gap Analysis run.
Instead of manually reading a forty-page spec and transcribing requirements by hand, you upload the document and let Catalio’s AI do the first pass. The heavy analysis runs on Catalio’s dedicated AI processing service, not inside the web application itself — you upload, the app hands the document off, and results come back as proposals once analysis completes. You spend your time reviewing, refining, and accepting the results rather than creating from scratch.
Where You Upload Determines What Happens
Document extraction isn’t a single pipeline anymore — what happens next depends on what the Artifact is attached to:
- Uploaded to an Application — Catalio compares the document against the source code of your connected GitHub repositories, looking for gaps between what the document describes and what the codebase actually does.
- Uploaded to an Initiative — Catalio treats the document as (or a contribution to) the Initiative’s PRD and enriches the Initiative’s specification from it.
Both paths hand off to the same AI processing service and both eventually produce reviewable Change Proposals, but the mechanics differ enough that it’s worth understanding both.
Path 1: Application Documents → Code Comparison
When you upload an Artifact to an Application that has one or more Repositories connected:
- Upload and hand-off. After the upload is saved, Catalio queues a comparison job for every repository mapped to that Application.
- Comparison on the AI service. Catalio’s AI processing service reads the document and compares it against the connected repository’s code, looking for requirements, capabilities, or behavior described in the document that isn’t reflected in the codebase (or vice versa).
- Proposals come back. As the comparison finds gaps, it posts them back to Catalio as Change Proposals — each one tagged with the entity type, a confidence score, and evidence linking back to the source document.
You need a connected repository for this to do anything. If the Application has no repository mapped yet, the upload is accepted but no comparison runs — there is currently no document-only extraction fallback for Applications. Connect a repository first (see Repositories), then upload your documents.
Path 2: Initiative Documents → PRD Enrichment
When you upload an Artifact to an Initiative, and the file is a PDF, Word document, Markdown, or plain text file:
- Upload and hand-off. After the upload is saved, Catalio queues an enrichment job for the Initiative’s PRD.
- Enrichment on the AI service. Catalio’s AI processing service reads the document and merges its content into the Initiative’s living specification.
- The PRD updates. The service writes the enriched specification back onto the Initiative — you’ll see the updated PRD on the Initiative’s page once processing completes.
Uploading a document to an Initiative doesn’t create Change Proposals directly — it updates the PRD. To turn a PRD into reviewable proposals (new requirements, components, or policies), run Gap Analysis against the Initiative, which reads the current PRD and produces proposals for anything it doesn’t find already captured in your catalog. See Gap Analysis for how that comparison works — it’s a related but separate step from the upload itself, and you trigger it deliberately rather than it running automatically after every upload.
Other artifact content types (or artifacts attached to something other than an Application or Initiative) are accepted as uploads but don’t currently trigger either pipeline.
What You’ll See While It Runs
Extraction and enrichment both run in the background, off the request that handled your upload. There’s no fixed turnaround time — it depends on the document’s length and current load on the AI service. Refresh the Application’s or Initiative’s proposal queue (or the Initiative’s PRD view) after a few minutes to check on progress; there is no separate “processing” indicator to watch on the artifact itself for this handoff.
How to Review Results
Once Change Proposals arrive:
- Accept a proposal to create or update the entity in your catalog
- Modify a proposal before accepting to correct names or descriptions
- Dismiss proposals that are duplicates, irrelevant, or incorrect
See Change Proposals for a full walkthrough of the review workflow, including how proposals are deduplicated against each other so re-running analysis doesn’t stack up repeats.
Best Practices
Connect repositories before uploading Application documents. Since comparison requires at least one mapped repository, connecting GitHub first means your first upload produces proposals immediately instead of sitting inert.
Use well-structured source documents. Documents with numbered lists, headings, and explicit “must”/“shall” language give the AI service clearer signal to work from than dense narrative prose.
Upload one document at a time and give it a few minutes. Both pipelines run asynchronously against an external service. Large batches queue up — check back rather than re-uploading if proposals don’t appear right away.
For Initiatives, treat PRD enrichment and Gap Analysis as two separate steps. Uploading a document updates the specification; running Gap Analysis is what turns that specification into proposals. Don’t expect proposals to appear just because you uploaded a document to an Initiative.
Dismiss liberally. It’s faster to dismiss noise than to fear missing something. You can always re-read the source document if you dismiss too aggressively.
Relationships at a Glance
| Related Concept | Relationship |
|---|---|
| Artifacts | The uploaded file that triggers extraction or enrichment |
| Application | Document + repository comparison is scoped to an Application |
| Repositories | A connected repository is required for Application-scoped comparison |
| Initiatives | Document uploads enrich the Initiative’s PRD |
| Gap Analysis | The deliberate next step that turns a PRD into Change Proposals |
| Change Proposals | The reviewable output of both extraction paths |
Next Steps
- Learn about Artifacts and where you can upload them
- Connect a Repository so Application document uploads have something to compare against
- Understand Change Proposals and the full review workflow
- Run Gap Analysis on an Initiative once its PRD is in good shape
Support
If Change Proposals don’t appear after an Application upload, first check that the Application has a connected, synced Repository — comparison does not run without one. If an Initiative’s PRD doesn’t update after uploading, confirm the file is a PDF, Word document, Markdown, or plain text file — other types aren’t picked up by PRD enrichment. If the right conditions are met and nothing happens after several minutes, contact support.
