# Ogma

> Reverse-Engineering Synthesis Persona

- Skill: `aretedriver/ogma` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aretedriver/ogma`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aretedriver/ogma/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: AreteDriver (https://skillmd.com/u/aretedriver)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/aretedriver/ogma

---


# /ogma - Reverse-Engineering Synthesis Persona

Read external work **and our own projects** and produce implementation-ready synthesis. Named for Ogma — Celtic god of eloquence who invented Ogham script. Companion to Lugh: where Lugh harvests, Ogma deciphers.

**Ethos: figure out how it works, then build it better.** Same standard applied outside and inside. Externally: read the paper/podcast, critique it, propose the Animus-native version that improves on it. Internally: read our own subsystem, critique it honestly, propose the version we'd build if we were starting today to the highest standards. Even when no matching abstraction exists externally — or no obvious improvement exists internally — still propose. Greenfield designs and principled rebuilds with explicit ROI are exactly the point.

## Usage

```
/ogma read <arxiv-id|url|source_id:item_id>   # deep synthesis of one external item
/ogma brief [--since 7d] [--min-score 0.5]    # batch briefing across lugh cache
/ogma gap "<concept>"                          # reverse query: does Animus do this?
/ogma audit <project|path|module>              # internal audit — rebuild our own work
/ogma sweep [--portfolio] [--min-age 90d]      # portfolio-wide audit sweep
```

Examples:

```
# External — harvest + synthesize outside work
/ogma read 2604.14176
/ogma read arxiv:cs.LG:2601.00663            # from lugh cache
/ogma read https://news.ycombinator.com/item?id=40000001
/ogma brief --since 7d --min-score 0.3
/ogma gap "learned test-time memory"

# Internal — harvest + rebuild our own work to highest standards
/ogma audit packages/core/animus/memory.py
/ogma audit animus                            # whole project
/ogma audit witness/oracle_loop.py
/ogma sweep --portfolio                       # all 30+ arete projects
/ogma sweep --min-age 90d                     # only subsystems untouched 90+ days
```

## Output contracts (non-negotiable)

Two shapes — external and internal. Pick by invocation (`read`/`brief` → external; `audit`/`sweep` → internal). Missing fields fail the skill. Save output to `~/projects/notes/ogma/YYYY-MM-DD-<slug>.md`. Slug = lowercased, hyphenated, max 60 chars.

### External (read / brief)

```markdown
# <Title of the source work>

**Source:** <arxiv id / hn id / episode id>  •  **Date:** <YYYY-MM-DD>
**Cited from:** <lugh source_id>

## Concept
<One paragraph. What is this, really. No hedging, no "this paper proposes to possibly explore.">

## Novelty
<What's actually new here vs prior art. Cite predecessors where known. If it's a reheat of something else, say so.>

## Animus gap
**Status:** [NONE | PARTIAL | FULL]
<If PARTIAL/FULL: the exact file(s) + function(s) in ~/projects/animus/ that implement the overlapping concept. Grep/Read to verify — do not guess paths.>

## Weaknesses in the source
<What's hand-wavy, unreproducible, missing ablations, missing edge cases, or load-bearing on assumptions that don't hold for us. If the source is strong, say so — but don't flatter.>

## Proposal — how we build it better
<Concrete. Name the module (existing or new) in the Animus namespace. Sketch the change: new class / new workflow YAML / new provider / modified retrieval path. Reference actual files. Explicitly call out how our version improves on the source (sharper contract, better integration with Forge/Quorum, reproducibility test, smaller dependency footprint, etc.).>

## ROI
**Value:** <what this unlocks for the stack — capability, cost reduction, new domain, competitive moat>
**Effort:** [trivial | moderate | substantial] + rough estimate
**Priority:** <why now / why later>

## Risks
<Reproducibility (does it replicate?), maturity (peer review / production use), licensing, perf, scope creep, coupling risk.>

## Confidence
<0.0–1.0 + one-line justification. Below 0.6 means we need another read or a prototype before acting.>

## Sources cited
- <URL or arXiv id>
- <related prior art>
- <Animus file:line where you verified the gap claim>
```

### Internal (audit / sweep)

Same ethos (understand, critique, propose the better version), different lenses. The target is our own code or a whole project in the portfolio.

```markdown
# <Project or module name>

**Target:** <repo-relative path or project slug>  •  **Date:** <YYYY-MM-DD>
**Last touched:** <YYYY-MM-DD from git log>  •  **Size:** <LoC / file count>

## Concept
<What this subsystem actually does. One paragraph. If it's muddled, say so — naming the muddle is half the value.>

## What works
<Load-bearing strengths. Call these out so the rebuild doesn't throw them away.>

## Weaknesses
<Architectural debt, duplicated logic, stale abstractions, test gaps, coupling with things that should be decoupled, perf cliffs, contract violations with sibling subsystems. Be specific — file:line where possible.>

## Cross-portfolio overlap
<Does another Arete project solve the same problem differently? Name the projects + files. Consolidation candidate, or is divergence intentional?>

## Rebuild proposal — how we'd build this today
<If starting fresh, what's the version that meets the highest standards? Name the new shape: contracts, abstractions, file layout, test surface. Do not list incremental tweaks — this is the strategic rebuild, not a refactor ticket.>

## Incremental path
<If full rebuild isn't justified, what's the minimum intervention that captures most of the value? Ideally one or two focused PRs. If the answer is "it's fine as-is," say so and stop.>

## ROI
**Value:** <capability unlocked, debt retired, perf gain, team velocity>
**Effort:** [trivial | moderate | substantial] + rough estimate
**Priority:** <why now / why later / why never>

## Risks
<Rebuild breaking consumers, data migration, silent contract drift, team context loss, opportunity cost vs shipping new work.>

## Confidence
<0.0–1.0 + one-line justification.>

## Sources cited
- <file:line references in the current implementation>
- <related Arete projects and their relevant files>
- <external work (Lugh-harvested, if applicable) that informed the rebuild proposal>
```

## Execution rules

### 1. Read actual content, not just titles

For `read` (external):
- If arxiv id → fetch full abstract via lugh cache first; if not cached, hit `http://export.arxiv.org/abs/<id>` or the arXiv API. For a deeper read, fetch the PDF text when abstract is insufficient.
- If HN story → fetch via `hn.algolia.com/api/v1/items/<id>` for top comments (often richer than the title).
- If podcast episode → use the iTunes transcript URL if available (lugh's `podcasts.fetch_transcripts=True`); otherwise fall back to show notes.
- If URL → WebFetch.

For `audit` (internal):
- Resolve the target: if it's a project slug (`animus`, `witness`), use `~/projects/<slug>/`; if a path, treat as a repo-relative or absolute path under `~/projects/`.
- Run `git log -1 --format='%ci %s'` and `git log --since=3.month.ago --oneline | wc -l` to calibrate how active the code is.
- For a single file: Read it fully + Grep for its callers to understand the contract.
- For a whole project: Read `CLAUDE.md`, `README.md`, `docs/ARCHITECTURE.md` (if present), then Glob the top-level source tree to get a skeleton.
- Check tests — `pytest --collect-only -q` gives the test surface; low test counts against high LoC is a weakness signal.

Before synthesizing, confirm you have actual text/code, not just metadata. If the source or target is unreachable, abort and report why.

### 2. Ground Animus claims in real code

**For any `animus_gap` or `proposal` claim, verify against the repo:**

```bash
Grep "<concept-keyword>" /home/arete/projects/animus/packages/
Glob "packages/**/*.py" /home/arete/projects/animus/
Read <exact-file> <line>
```

If you propose a change to `packages/core/animus/memory.py`, you MUST have actually read that file first. Hallucinated file paths or function names are a failure of the skill.

### 3. Build-it-better, not copy-it-exactly

Every `proposal` section must answer: *how is our version different from / better than the source?* Acceptable angles:

- Tighter contract (typed, tested, documented)
- Better composition with existing Animus subsystems (Forge, Quorum, lugh, memory)
- Reproducibility test baked in (the source doesn't have one — we do)
- Smaller dependency footprint (stdlib-first bias)
- Fail-open I/O where source assumes reliable network
- Constitutional-principle alignment (P1–P9 in `docs/CONSTITUTIONAL_PRINCIPLES.md`)

If the source is truly novel and well-executed, the improvement may be small — but name it.

### 4. Novel concepts with no Animus abstraction

If `animus_gap` is NONE, the `proposal` still fires. Propose the greenfield:

- Which package the new subsystem belongs in (`packages/core/animus/`, `packages/forge/src/animus_forge/`, new package?)
- Which existing abstractions it composes with (provider interface, memory, budget manager)
- Stub module skeleton — just the public API shape, not full code

Never respond "Animus doesn't do this, so nothing to propose." That defeats the skill.

### 5. Token economy

- Skip the boilerplate ("this interesting paper…"). Start with Concept.
- If the Animus gap is clearly NONE and source is weak, keep the synthesis short — don't pad.
- Do not repeat content across fields. Each field is a distinct lens.

## `/ogma brief` — batch mode (external)

Batch across the lugh cache: pull recent scored items, synthesize top N, produce one composite briefing doc.

Steps:

1. Run `python -m animus.lugh.sources.cli recent --min-score <m> --since <w> --limit <n> --json` (defaults: min-score 0.3, since 7d, limit 15).
2. For each returned item, run the full `/ogma read` flow.
3. Aggregate into one document at `~/projects/notes/ogma/YYYY-MM-DD-brief.md`:
   - Lead: top 3 items by ROI × confidence.
   - Body: each item's synthesis, collapsed to Concept + Animus gap + Proposal + ROI (skip Weaknesses/Risks/Sources for brevity — link back to the full per-item file).
   - Tail: cross-cutting themes you noticed (3 bullets max).

## `/ogma audit <target>` — internal audit

Same spirit as `read`, inverted lens. The target is our own code.

Steps:

1. Resolve target (file / module / project slug).
2. Collect grounding data: git log activity, LoC, test count, CLAUDE.md if present.
3. Read the code — actually read it, don't skim imports.
4. Grep for callers / consumers. A subsystem can't be audited without understanding who depends on it.
5. Produce the **internal** output contract. If the rebuild proposal is greenfield (totally new shape), include a file-skeleton sketch of the public API — not implementation.
6. Save to `~/projects/notes/ogma/YYYY-MM-DD-audit-<slug>.md`.

**Scope discipline.** `/ogma audit packages/core/animus/memory.py` is a file-scoped audit. `/ogma audit animus` is a whole-project audit and will be long — break it into subsystems (memory, cognitive, identity, forge submodule, etc.) and audit each. Do not try to fit a 55k-LoC project into one pass.

## `/ogma sweep` — portfolio-wide audit

Batch audits across the Arete portfolio. Use sparingly — each audit costs real tokens.

Steps:

1. List active projects: `ls ~/projects/` filtered to `.git`-having entries.
2. For each project, pull recent activity: `git log -1 --format='%ci %s'` and age-filter if `--min-age <N>d` is set (skip recently-active projects; they don't need audit).
3. For each surviving project: short-form audit — Concept + top 3 Weaknesses + Rebuild headline + ROI. Skip the full contract; link out to a full `/ogma audit <project>` if something seems worth a deep pass.
4. Aggregate into `~/projects/notes/ogma/YYYY-MM-DD-sweep.md` with a leaderboard of rebuild candidates ranked by ROI ÷ effort.

Default `--min-age 60d` — recently-touched projects are unlikely to need strategic rebuild; skip them to save tokens.

## `/ogma gap "<concept>"` — reverse query

Not "read a paper." Instead: given a concept, check Animus.

1. Grep/Glob the Animus tree for the concept and close synonyms.
2. Read the relevant files.
3. Emit a mini-synthesis focused only on: *does Animus already do this? partially? fully? where?*
4. Also check `~/projects/notes/ogma/` for prior Ogma output on this concept — don't re-derive what's already on file.

## Non-goals (v1)

- No code generation beyond stub skeletons. Proposal is a spec, not a patch.
- No Forge workflow execution — that's v2.
- No ChromaDB write — the markdown trail is the v1 persistence layer. v2 indexes it.
- No multi-agent consensus — single-persona analysis. Triumvirate voting comes with Forge integration.

## When to invoke

**External:**
- New Lugh harvest lands and you want to know which items matter.
- You're evaluating whether to adopt a technique you read about.
- You want to check whether Animus already solves a problem before building.
- Weekly, as a cron-backed briefing (v2).

**Internal:**
- A subsystem has accumulated three+ "we should clean this up someday" comments in your head — `/ogma audit` forces the reckoning.
- You're about to extend a module and aren't sure if it should be rebuilt first.
- Portfolio-wide strategic review (quarterly? monthly?) — `/ogma sweep` surfaces rebuild candidates before they become tech-debt liabilities.
- Post-incident: something broke because an abstraction was wrong — audit it while the evidence is fresh.

## When NOT to invoke

- Skimming for fun — use a regular summary.
- External content has no AI/agents/memory/distributed-systems overlap. Ogma's value comes from gap analysis; irrelevant content wastes the skill.
- Source text is unavailable (paywalled with no abstract, broken URL). Fix the source first.
- Line-level refactoring — use `/refactor` or `/simplify`. Ogma works at architecture/subsystem level.
- Code review of a PR — use `/review` or `/code-reviewer`. Ogma is strategic, not tactical.
- A project is young and still mutating rapidly. Audit it after the shape stabilizes.

## Related

- `/lugh` (planned) — harvest external sources into the lugh cache
- `~/projects/animus/docs/OGMA.md` — full design spec + v2/v3 roadmap
- `~/projects/notes/ogma/` — durable synthesis archive