← ClaudeAtlas

ax-add-ingest-stagelisted

Use when adding a new ingest stage or a new SurrealDB table to the ax graph. Encodes the exact registration gotchas that fail CI if missed.
Necmttn/ax · ★ 30 · AI & Automation · score 70
Install: claude install-skill Necmttn/ax
# Adding an ingest stage / table to ax Hard-won checklist - each step below has a CI gate that fails if you skip it. ## New SurrealDB table 1. Add the `DEFINE TABLE ... SCHEMAFULL` + fields to `packages/schema/src/schema.surql` (top-level fields explicit; nested objects → JSON-encoded `string`; datetimes via JS `Date`). 2. **Register it in `SCHEMA_TABLES`** (`apps/axctl/src/queries/insights.ts`) - a mirror test diffs `DEFINE TABLE` names vs `SCHEMA_TABLES` and **fails CI** if missing. 3. In a worktree, run `bun install` so `@ax/schema` resolves to the worktree copy (not the main tree's symlink) before the mirror test will pass. ## New `derive`-tagged ingest stage 1. Co-locate the `StageDef` at the bottom of the stage file (mirror `apps/axctl/src/ingest/derive-opportunities.ts`): `export const FooKey = Schema.Literal("foo")` + `fooStage`. 2. Register in `apps/axctl/src/ingest/stage/registry.ts`: add the import, add `FooKey` to the `IngestStageKey` `Schema.Union([...])`, add `fooStage` to `ALL_STAGES`. 3. **Update `apps/axctl/src/cli/effect-cli.test.ts`**: bump the `resolveIngestStages: default runs every stage` `.toHaveLength(N)` by 1, and add your key (sorted) to the `--derive-only` list. CI fails otherwise. 4. **Isolate failures**: wrap the stage body in `Effect.catchCause` returning a zero-row stat, so a stage error never aborts the surrounding ingest. ## New CLI subcommand Document it in **BOTH** cli-reference gates or CI fails: `docs/cli.md` (or README) + `apps/site/p