| name | Transitrix Knowledge Store |
| description | Ingest raw source material into the OKF single-repo MVP knowledge store — assess, archive, route to the OKF track (extract drafts → verify → human review → promote to knowledge/) and/or the Canon track (extract Transitrix primitives → PR to canon/), and log every decision. |
| when_to_use | User says "ingest this document", "add this to the knowledge store", "extract knowledge objects from this", "route this to canon", or drops a file into `_intake/inbox/` and wants it processed. |
| min_version | 1.0.0 |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep |
Transitrix Knowledge Store Skill
Processes raw source material through the OKF single-repo MVP knowledge store. All work is done by the agent using Read/Write/Edit tools — no external CLI required. A human reviews and approves before anything lands in knowledge/ or canon/.
The one rule
Propose, never promote unilaterally. For the OKF track, the agent writes drafts to _intake/drafts/ only — never directly to knowledge/. For the Canon track, the agent opens a PR to canon/ — it never merges it. The human gate is the only admission authority.
Run the quality gates before and after promotion. After writing drafts (Step 4a) and again after promoting approved objects to knowledge/ (Step 4d), run the knowledge-store linter and fix every error:
python3 tools/knowledge_store_lint.py .
The linter enforces Gates 1–6 from patterns/knowledge-store.md §Quality gates. Errors block promotion; warnings require explicit human acknowledgment in _intake/log.md. See tests/README.md for the KS-001..017 code reference.
Step 0 — Check the MVP structure
Verify the repo has the expected layout:
_intake/
inbox/ ← source files waiting for processing
originals/ ← raw source files (gitignored)
processed/ ← OKF source-document records (committed)
drafts/ ← proposer output (Gate 6 — not cited; not promoted)
log.md ← all events: [route] / [admit] / [ambig] / [conflicts] / [assert]
knowledge/
index.md ← bundle index (auto-maintained)
<concept>.md ← individual OKF knowledge objects
If _intake/ or knowledge/ are missing, scaffold them now. Create _intake/drafts/ if absent. Copy the initialisation content from patterns/knowledge-store.md §Templates. Add gitignore entries for _intake/inbox/* and _intake/originals/* (drafts MAY be committed for audit or gitignored for ephemeral runs).
Step 1 — Assess the document
Read the source document from _intake/inbox/. Determine:
confidence: — curator's epistemic assessment of the signal quality:
observed — first-hand account, direct evidence, system outputinferred — derived from evidence; logical but not stated explicitlyassumed — working assumption, hearsay, or low-corroboration claim
tracks: — which ingestion tracks apply (one or both):
okf — contains knowledge objects: insights, findings, concepts, questions worth curatingcanon — contains Transitrix primitives: DRIVERs, GOALs, CHANGEs, CAPABILITYs, etc.
- Proposed
description: — one-sentence summary of the document
State your assessment to the user before proceeding.
Step 2 — Archive to processed/
Copy the source file reference to _intake/processed/ as an OKF source-document record using the template at patterns/knowledge-store-templates/okf-source-document.md.
Fill in:
title: — document filename or stated titledescription: — one-sentence summary from Step 1source: — original file path or URI (e.g. _intake/inbox/filename.md or a web URL)source_hash: — SHA-256 of the source file (sha256sum / Get-FileHash)created_at: — today's dateconfidence: — from Step 1tags: — inferred topic tagstracks: — from Step 1
Filename convention: YYYY-MM-DD-<slug>.md where slug is a 3–5 word kebab-case summary.
Move the source file from _intake/inbox/ to _intake/originals/ (gitignored, kept for traceability).
Step 3 — Log the routing decision
Append to _intake/log.md:
## YYYY-MM-DD
- [route] `<processed-filename>` → tracks: [okf, canon] | confidence: observed | <one-line reason>
Step 4 — OKF track (if okf in tracks)
4a — Propose drafts (Gate 6)
Read the source document from _intake/originals/ (or the processed record). Using the extraction prompt at prompts/extract-okf.md, extract candidate knowledge objects and write each to _intake/drafts/<slug>.md using the template at patterns/knowledge-store-templates/okf-knowledge-object-draft.md.
Each draft:
- has a clear, discrete idea (one concept per file)
- carries
type:, confidence:, source:, description: as for promoted objects
- carries
review_status: — ready (grounded, linter-clean candidate), ambiguous (needs human judgement; set non-empty ambiguity_note:), or blocked (too vague to review; skip by default)
- carries
mapping: / conflicts_with: when relating to existing knowledge (Gate 2)
Do not write to knowledge/ at this step.
4b — Verify drafts
Follow prompts/verify-drafts.md. Run python3 tools/knowledge_store_lint.py . and fix every error on draft paths before presenting the batch. Then present drafts grouped by review_status (ready / ambiguous / blocked). State what was skipped and why.
4c — User review gate
Wait for the user to approve, reject, or revise each draft. Do not promote anything to knowledge/ until you have explicit approval. For ambiguous drafts, log a hold (Step 4f) until resolved.
4d — Dispose approved drafts
For each approved draft, copy to knowledge/<slug>.md using patterns/knowledge-store-templates/okf-knowledge-object.md. Remove review_status and ambiguity_note from frontmatter. Delete the corresponding file under _intake/drafts/.
Run python3 tools/knowledge_store_lint.py . again. Fix every error before proceeding. Surface warnings (KS-008, KS-010, KS-013) for explicit acknowledgment.
4e — Regenerate knowledge/index.md
After all approved objects are promoted, update knowledge/index.md to include new or updated rows. Do not remove rows for existing objects not touched in this ingestion.
4f — Log admit decisions
Append to _intake/log.md for each promoted object:
- [admit] `<knowledge-object-filename>` ← `<source-document-filename>` | approved | <one-line note>
For each rejected draft:
- [admit] rejected: "<title>" | reason: <one-line reason>
For each ambiguous draft held for review:
- [ambig] `<draft-filename>` | <ambiguity_note one-liner> | held for review
For each object held because it conflicts with existing knowledge (not admitted until reviewed):
- [conflicts] `<knowledge-object-filename>` vs `<conflicts_with-target>` | held for review | <one-line note>
Step 5 — Canon track (if canon in tracks)
5a — Extract Transitrix primitives
Using the extraction prompt at prompts/extract-canon.md, identify candidate Transitrix elements (DRIVER, GOAL, CHANGE, CAPABILITY, ACTOR, ROLE, PROCESS, APPLICATION, PRODUCT, etc.) and typed relations. Be conservative on relations — only propose a relation when the source explicitly states the connection.
For each candidate, draft a YAML block in the format expected by canon/elements/<type>/:
type: DRIVER
id: DRIV-NNN
name: ""
description: ""
derived_from: [<processed-source-document-path>]
admitted_to: pending
extraction_confidence: high | medium | low
5b — Open PR
Create a branch knowledge-store/ingest-<YYYY-MM-DD>-<slug> and commit the candidate YAML files. Open a PR titled [Knowledge Store] Ingest: <source-document-title>.
PR body must include:
- Link to the processed source-document record
- Table of proposed elements with type, name, and extraction_confidence
- Note on any relations proposed
- Instruction: "Review, revise IDs to avoid conflicts, and merge when satisfied."
5c — Log assertion outcome (after PR is merged or closed)
Once the user reports the PR outcome, append to _intake/log.md:
- [assert] PR #<number> merged | admitted: [DRIV-NNN, GOAL-NNN, ...] | source: <processed-filename>
Or for rejected:
- [assert] PR #<number> closed without merge | reason: <one-line>
What this skill does NOT do
- Does not merge PRs. The canon gate is always a human.
- Does not write to
knowledge/ before user review of drafts (Gate 6 — drafts land in _intake/drafts/ only).
- Does not assign
extraction_confidence: high to relations — relations are flagged medium or lower unless the source text is unambiguous.
- Does not remove existing knowledge objects. Only add or update.
- Does not process multiple documents in the same run unless explicitly asked — one source per run keeps the log clean.
