| name | ingest |
| description | Create or update a single OKF concept file from raw input. Use when the user wants to document a specific table, metric, API, service, or concept in the knowledge base — even if they say "add this to the okf", "documenta essa tabela", "cria um conceito pra isso", "adiciona no knowledge base", "register this API", or pastes a schema/description and says to save it. If no OKF files exist yet, suggest /mega-brain:init first. |
ingest — OKF Concept Writer
Turns raw input (schema dump, API doc, user description, table definition) into one OKF-formatted .md file committed to the knowledge base.
Before writing
Look for existing OKF files: any .md with type: frontmatter, or index.md / log.md in the project. If none exist, stop and tell the user to run /mega-brain:init first.
If .mega-brain.json defines dir, save new concepts under that directory. Otherwise, choose a sensible location (docs/, project root, etc.) consistent with existing OKF files.
Check if a concept with the same name already exists. If so, ask whether to update it or create a new one.
Output format
One .md file per concept. Only type is required:
---
type: <concept type>
title: <display name>
description: <one sentence, plain language, no jargon>
resource: <URL to the actual resource, if any>
tags: [<tag1>, <tag2>]
timestamp: <ISO 8601 date>
---
<body: exact schema, formula, join patterns, examples, caveats>
Common types
| Type | Use for |
|---|
BigQuery Table | BQ tables with schema |
BigQuery Dataset | BQ datasets |
Table | Non-BQ database tables |
Metric | KPI or business metric with formula |
API | REST/GraphQL endpoints |
Runbook | Operational procedures |
Concept | Business or domain terminology |
Service | Internal microservices |
Pipeline | ETL or data pipelines |
Types are freeform — add your own.
Process
- Read the source material
- Identify the concept type and canonical name
- Write
description: one sentence, plain language
- Add
resource URL if there's a live resource (BQ console URL, API endpoint, dashboard)
- Write the body with exact values — preserve field names, types, and formulas as-is; do not generalize
- Link to related concepts with
[Name](relative-path.md) — this builds the knowledge graph
- Save next to related OKF files (e.g.
docs/tables/<slug>.md or <config-dir>/tables/<slug>.md)
- Add one line to
index.md: - [Title](path) — description
- Append to
log.md: <date> — added <title>
Updating an existing entry
- Update
timestamp
- Preserve existing wikilinks unless explicitly removing them
- Keep
description to one sentence — push additional detail into the body
