manuelmauro/arkouda/use-arkouda

Using arkouda

In repositories that record decisions and requirements as Markdown files with YAML frontmatter (conventionally under docs/adr/ and docs/prd/), arkouda is the CLI for finding, reading, validating, and scaffolding them. Before you decide, check what's already been decided. Before you build, check what's already required. After you decide, capture it.

An arkouda directory is an Open Knowledge Format (OKF) v0.2 knowledge bundle: each document is a concept whose id is its path within the bundle without the .md suffix (security/mtls.md → security/mtls). index.md and log.md are reserved by OKF and are never concepts.

If a repo has no such directory yet but the arkouda binary is installed, this skill is also the right one to reach for: arkouda new enforces the schema from the first file.

Concept types

Arkouda has two built-in types, and picking the wrong one produces a document that fails arkouda check.

The two are linked from the PRD side: a PRD's decisions frontmatter key lists the concept ids of the ADRs that shaped it. Traverse from a requirement to its rationale by reading that key — never by restating the decision inside the PRD.

Apart from `Status`, the two share no section headings. A PRD has no ## Context; its motivation is ## Problem. Asking for a section the concept's type doesn't have is an error, not a near-miss. If you don't know which type a concept is, run arkouda list -l and read the type column, or just omit the section name and let arkouda pick the primary one.

The project may define more

A project can declare its own types with `[[types]]` in `.arkoudarc.toml`, and it can replace the built-in ADR or PRD contract with its own. So the two tables above describe arkouda's defaults, not necessarily this repo. Before you scaffold anything in an unfamiliar repo:

arkouda --help     # nothing about types here — the type set is per project
arkouda list -l    # the type column shows which types are actually in use
 
# `.arkoudarc.toml` is discovered by walking *up* from the working directory,
# so reading only `./.arkoudarc.toml` misses the config from a nested dir.
d=$PWD; until [ -f "$d/.arkoudarc.toml" ] || [ "$d" = / ]; do d=$(dirname "$d"); done
cat "$d/.arkoudarc.toml" 2>/dev/null   # the authoritative list of this repo's types

A [[types]] table gives its type a slug (what --type takes), an okf_type (what its documents declare), a status lifecycle, optionally required_sections and a primary_section, a default_dir, and optionally a template. Read the table and follow it exactly as you would the built-in contracts — arkouda new --type <slug> scaffolds from it, and arkouda check enforces it.

arkouda new --type <slug> with an unknown slug lists the slugs that do exist, so that error is the fastest way to see this repo's types if there is no config file to read.

When to use

Reach for this skill any time you're about to make a non-trivial decision or start non-trivial work. Concretely:

• Before writing code that picks a library, framework, datastore, encoding, transport, or other "we now depend on X" commitment. (ADR)
• Before changing a public interface, file layout, schema, naming convention, or directory structure. (ADR)
• Before refactoring away from a pattern you didn't introduce — you may be about to undo a deliberate decision. (ADR)
• Before building a feature of any size: check whether a PRD already defines its scope, its non-goals, and what success means. (PRD)
• When the user asks "did we ever decide on X?", "why is it done this way?", "what are we building?", or "is X in scope?".
• When the user asks for a new ADR or PRD, or to mark one superseded.
• Whenever you land in an unfamiliar repo with an arkouda collection.

A 5-second arkouda list | xargs rg -i <topic> is cheaper than redoing a debate that's already in the file, or building something a PRD explicitly listed as a non-goal.

Philosophy

Three principles shape arkouda's behaviour, and explain why some defaults look minimal:

• Defer to Unix tools. Arkouda earns subcommands only where standard shell tools (rg, grep, cat, awk, xargs) cannot. Content search, full-file printing, counting, and slicing are left to the shell — the CLI emits structured output you compose with the rest of your toolbox. Hence: no search, no full-file show.
• Primary-section defaults. arkouda list prints one path per line (no header, no padding) so it pipes cleanly. Each type has one section carrying its substance, so arkouda section <id> with no section name prints that one — ## Decision for an ADR, ## Requirements for a PRD. Supporting sections are named explicitly.
• Standard format over bespoke. Documents are stored as OKF concepts, and a concept's type is a frontmatter field, so any OKF-aware consumer can read them and one bundle can hold both types.

The source rationale lives in arkouda's own repo, in the ADRs `defer-to-unix-tools`, `ls-style-list-and-decision`, `adopt-okf`, and `support-product-requirements-documents`.

Where documents live

The location varies between repos. Don't hardcode docs/adr/ in pipelines — ask arkouda. Run `arkouda list` to get the actual paths for the repo you're in.

Arkouda finds bundles; nothing configures them. A bundle is the topmost directory that directly contains an OKF concept — a non-reserved .md whose frontmatter declares a type — and everything beneath it belongs to that bundle, so a nested concept keeps its path in its id. list, check, section, and index read every bundle found; type comes from frontmatter, never from the directory.

The walk skips .git, node_modules, target, vendor, dist, build, out, .next, .venv, venv, __pycache__, coverage, and hidden directories.

To scope one invocation to part of the tree, use --dir <path> or ADR_DIR=<path>. It narrows the walk rather than declaring a root.

arkouda new writes into the first bundle that already holds a concept of the type it is creating, then the --dir you named, then that type's default_dir.

`.arkoudarc.toml` no longer says where bundles are. A dirs key is an error naming its replacement; delete it. The file's remaining jobs are declaring [[types]] and the telemetry toggle.

A concept id is the document's path within its bundle, minus the .md suffix — not just the filename. A top-level use-postgres.md has the id use-postgres; a nested security/mtls.md has the id security/mtls. arkouda section accepts the full concept id (security/mtls), the bare stem (mtls), or the filename.

Commands

Five subcommands, each doing something the shell can't:

• `arkouda list [--sort id|timestamp|status] [--type <slug>] [-l]` — one path per line. Pipe straight into xargs/rg/cat/wc. With -l, a headerless ID TYPE STATUS TIMESTAMP PATH TITLE — DESCRIPTION table for human skimming and for awk. --type filters by frontmatter type; valid slugs are this project's, not a fixed adr|prd.
• `arkouda section <id> [<name>]` — body of that concept's primary section (Decision for an ADR, Requirements for a PRD). Give a <name> for any other heading (context, consequences, problem, non-goals, success metrics, status, or custom). Errors if the section is missing. For the full file, resolve the path through arkouda list and cat it.
• `arkouda check` — validates in three tiers: OKF conformance for every concept, arkouda's frontmatter profile for concepts whose type the project configures, and that type's status vocabulary and required sections. Exit 0 clean, 1 on any error. Each diagnostic carries a code (E000–E015) and a fix hint. Warnings never fail the run. A concept whose type no [[types]] table configures is checked for OKF conformance only and warned about (E005) — it is neither skipped nor a failure.
• `arkouda new "<title>" [--type <slug>] [--id <slug>] [--status <value>] [--description "<one-line summary>"]` — scaffold a new concept with today's date, from that type's template. Defaults to --type adr. That default keeps working when a project redefines the adr slug — you get its contract instead of the built-in one — and fails only when the project has no adr slug at all, in which case the error names the slugs it does have. --status must come from the chosen type's own vocabulary and defaults to the first of its lifecycle (proposed for an ADR, draft for a PRD); it is written to lifecycle, and the OKF status it projects onto is written alongside it. Default id is a slug from the title. The description should summarize what was decided or what is being built, not just the topic. Refreshes index.md if the bundle has one.
• `arkouda index` — regenerate each bundle's index.md, an OKF §6 listing of every concept under # <Type> then ## <Status>. Read it to see the whole collection at a glance without opening any file.

Global flags: --dir <path> (also ADR_DIR), -q/--quiet. Run arkouda --help or arkouda <subcommand> --help for the authoritative surface.

There is intentionally no search subcommand and no full-file show — rg/grep and cat already do those.

One-liners

arkouda list is the path source — it's where the documents actually are in this repo.

# Orient in an unfamiliar repo — the type column tells you what's here
arkouda list -l && arkouda check
 
# Paths of everything (for piping)
arkouda list
 
# Search for a topic — let list provide the search roots
arkouda list | xargs rg -i <topic>
 
# Read the substance of a specific concept (Decision, or Requirements)
arkouda section use-postgres
 
# Read another section instead
arkouda section use-postgres consequences
arkouda section bulk-import non-goals
 
# Read the whole document — resolve the path through list
cat "$(arkouda list | grep -F /use-postgres.md)"