Pipeline Stages
Every forge module runs the same six-stage pipeline. Each stage transforms the knowledge base incrementally.
1. Ingest
Section titled “1. Ingest”Scanners pull data from your domain sources: git repos, GitHub/GitLab/Jira issues, PDFs, academic papers, markdown docs.
Each forge module has its own scanners optimized for its domain. The code forge reads source files and git history. The paper forge parses PDFs and fetches arXiv metadata. The product forge pulls issues from the GitHub API.
2. Extract
Section titled “2. Extract”The LLM analyzes source material and proposes structured beliefs with:
- node_id — a unique, kebab-case identifier
- text — the belief content, one fact per node
- source — where the belief came from (file path, URL, paper DOI)
- justification links — which other beliefs support this one
Extraction turns unstructured documents into structured, justified knowledge.
3. Derive
Section titled “3. Derive”The LLM proposes new beliefs by combining existing ones. This stage explores unmapped concept space — it is deliberately unconstrained to enable discovery of novel insights and connections.
A derived belief always has an sl (support list) pointing at the beliefs it was derived from. This makes the reasoning chain inspectable via reasons explain.
4. Review
Section titled “4. Review”The LLM adversarially evaluates derived beliefs. It:
- Challenges weak justifications
- Flags smuggled conjunctions (multiple unrelated claims in one node)
- Identifies near-duplicates
- Retracts what does not survive scrutiny
This is the quality gate. Beliefs that pass review are justified and defended. Beliefs that fail are retracted with a recorded reason.
5. Repair
Section titled “5. Repair”Fixes structural problems that review identified:
- Smuggled conjunctions — splits multi-claim nodes into individual beliefs
- Broken justification chains — reconnects or removes dangling references
- Unjustified premises — flags premises that need sources
- Near-duplicates — merges or supersedes redundant beliefs
6. Export
Section titled “6. Export”Produces output in your choice of format:
| Format | File | Use case |
|---|---|---|
| SQLite | reasons.db |
Primary format. Use with Reasons.app, CLI, MCP |
| JSON | network.json |
Machine-readable graph export |
| Markdown | beliefs.md |
Human-readable summary |
| Static wiki | dist/ |
Browsable HTML site, deployable to Cloudflare Pages |
The SQLite format is the universal interchange point between Reasons Forge (production) and Reasons.app (consumption).