You upload a file. The pipeline does the rest.
Name your file correctly, drop it into
Name your file correctly, drop it into
data/uploads/ on GitHub, commit — and within minutes the ingestion, synthesis, and review agents run automatically. Check the Pipeline tab for results.1
Name Your File Correctly
The pipeline infers the value chain from the filename — this is the only manual step you must get right.
Rule: Start the filename with the value chain code (e.g.
VC01_), then a short description, then the year.Format: VCxx_description_year.ext
| Code | Value Chain | Good filename example |
|---|---|---|
| VC01 | Iron & Steel | VC01_market_survey_2024.pdf |
| VC02 | Copper & Allied Metals | VC02_production_data_2024.xlsx |
| VC03 | Automotive | VC03_KMC_capacity_report.docx |
| VC04 | Textiles & Garments | VC04_firms_survey_2025.pdf |
| VC05 | Pharmaceuticals | VC05_NDA_register_2024.xlsx |
| VC06 | Petrochemicals & Fertilizers | VC06_kabalega_project_brief.pdf |
| VC07 | Sugar & Confectionery | VC07_USPA_statistics_2024.pdf |
| VC08 | Plastics & Packaging | VC08_industry_association_data.xlsx |
| VC09 | Cement & Building Materials | VC09_UCHA_capacity_2024.docx |
If the filename does NOT start with VCxx, the pipeline will try to guess the chain from keywords in the content. This sometimes works, but can result in data going to the wrong chain. Always use the VCxx prefix.
Accepted file types: PDF, DOCX, XLSX, CSV. Maximum size: no hard limit (content is truncated at 80,000 characters for Claude processing).
2
Upload to data/uploads/ on GitHub
Navigate to the folder and drag-drop or click "Add file".
MTIC-Uganda / industrial_diagnostic_study
Branch: main
Drop files here to upload, or use Add file →
↑ Go to file
+ Add file ▾
.gitkeepnaming convention docs
VC01_market_survey_2024.pdf⟵ your file goes here
Two ways to upload:
a) Browser drag-drop: Navigate to
b) Git on your laptop: Copy the file into
a) Browser drag-drop: Navigate to
data/uploads/ → click "Add file" → "Upload files" → drag your file → scroll down → write a short commit message → click "Commit changes".b) Git on your laptop: Copy the file into
data/uploads/, then git add → git commit → git push.
3
Write a Commit Message and Commit
The commit message is how the team knows what was uploaded — keep it short and descriptive.
Commit changes
data: add VC01 Iron & Steel market survey 2024
Source: Uganda Bureau of Standards / Commissioner's office ...
Cancel
Commit changes
Good commit message format: data: add VC<XX> <short description> <year>
4
The Pipeline Runs Automatically
GitHub Actions detects the upload and triggers three agents in sequence.
📤 You upload
data/uploads/
data/uploads/
→
📥 Ingest Agent
mines doc + trusted sources
mines doc + trusted sources
→
✍️ Synthesis Agent
writes diagnostic chapter
writes diagnostic chapter
→
✅ Review Agent
validates 32 checks
validates 32 checks
PUBLISH verdict: The review agent opens a GitHub Pull Request with the finished chapter. Jerome or Solomon merges it to publish.
REVISION verdict: The review agent writes a revision notice to
data/revision/ and sends a WhatsApp notification. The notice explains exactly what data is missing and which fields need to be filled.
How long does it take?
| Ingest Agent | 1–3 minutes (depends on document size and Claude processing time) |
| Synthesis Agent | 2–5 minutes (Claude writes the full chapter) |
| Review Agent | 1–3 minutes (Claude evaluates 32 quality gate checks) |
Total: typically 5–12 minutes from commit to verdict.
5
Check the Pipeline Status
Two places to see what happened: the dashboard Pipeline tab, and GitHub Actions.
🔄 Dashboard — Pipeline Tab
Go to the main dashboard → click the 🔄 Pipeline tab. Each value chain shows its Ingest / Synthesise / Review status at a glance, plus the revision summary if something needs fixing.
Open Dashboard →⚙️ GitHub Actions
For detailed logs: go to the repo → Actions tab → find the workflow run triggered by your commit → click "Ingestion Agent", "Synthesis Agent", or "Review Agent" to see the full output.
All workflows
Deploy MTIC Value Chains App
data: add VC01 Iron & Steel market survey 2024 · main · 8 minutes ago
✓ completed
data: add VC01 Iron & Steel market survey 2024 · main · 8 minutes ago
📥 Ingestion Agent · 2m 14s
✍️ Synthesis Agent · 4m 07s
🔍 Review Agent · 2m 53s — 3 mandatory failures
6
If Revision Is Required — Read the Notice
The review agent writes exactly what is missing and what you need to do.
A REVISION verdict does not mean your document was wrong — it means some mandatory data fields are still empty after all three ingestion methods ran. The notice tells you which fields and what source to consult.
## Revision Notice — Iron & Steel (VC01)
Run: 20260615T103412Z | Verdict: RETURN_FOR_REVISION
### E-01 — STAGE_1_EVIDENCE
Check: All evidence_required=true fields have populated values or explicit not_available with source note.
Failing fields: D1.02, D1.03, D3.01
Fix required: Add TradeMap export/import figures for Iron & Steel (HS 72). Run the trusted_source method manually or upload a TradeMap CSV named VC01_trademap_2024.csv.
## Summary
Three evidence-required fields are missing trade volume data. Upload a TradeMap CSV for VC01 to resolve all three failures in one run.
What to do:
- Read the revision notice — it names the exact field IDs and the data source needed.
- Find the missing data from the suggested source (e.g. TradeMap, UBOS, firm records).
- Save it as a new file named with the correct VCxx prefix.
- Upload to
data/uploads/and commit — the pipeline re-runs automatically.
7
Approving Gap-Fill Proposals (Optional)
When the pipeline cannot find data anywhere, it proposes candidate values for your review.
Sometimes the ingestion agent exhausts all three methods (doc mining, trusted sources, web search) and still cannot find a value for a mandatory field. In that case it proposes a candidate from general knowledge and opens a GitHub Pull Request for your approval.
Your merge = your approval. Before merging a gap-fill PR, verify each proposed value by clicking the
source_url link in the JSON file. If a value is wrong, edit it before merging. Closing without merging = rejection — nothing enters the dataset.Data review: web gap-fill proposals 2026-06-15
jnuwabaasa-spec opened this pull request · 1 file changed
The ingestion agent could not find values for some mandatory fields.
It has proposed candidate values from general knowledge.
✔ Review each value in data/proposed/web_gap_fill_20260615.json
Check the source_url for each field. If correct: merge. If wrong: edit first.
Merge pull request ✓
Close pull request
That's the whole workflow. Name → Upload → Commit → Wait 5–12 min → Check Pipeline tab. If revision required, follow the notice and upload again. The pipeline is self-correcting — every upload gets you closer to a published chapter.