ingest

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

1. Read the source material
2. Identify the concept type and canonical name
3. Write description: one sentence, plain language
4. Add resource URL if there's a live resource (BQ console URL, API endpoint, dashboard)
5. Write the body with exact values — preserve field names, types, and formulas as-is; do not generalize
6. Link to related concepts with [Name](relative-path.md) — this builds the knowledge graph
7. Save next to related OKF files (e.g. docs/tables/<slug>.md or <config-dir>/tables/<slug>.md)
8. Add one line to index.md: - [Title](path) — description
9. 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