Skip to main content

Primitives

Kleio writes everything as signals. A signal is a small structured record with provenance attached: who emitted it, from where, when, and tied to which repo / commit / branch when relevant.

There are three signal shapes that matter day-to-day:

PrimitiveWhat it capturesWhen to log it
DecisionA direction you committed to, with rationale, confidence, and alternatives considered.Before implementing a non-trivial choice.
CheckpointA meaningful slice of implementation work, with validation status, files touched, and what was deferred.After shipping a coherent slice.
Work-item captureA discovered piece of follow-up work (bug, debt, feature gap).During development, the moment you notice it.

Everything else — PR reviews, CI runs, security alerts, commits — is also stored as a signal but flows in automatically through the GitHub App. You don't log those by hand.

Decisions​

A decision records a choice, not the implementation of it.

Required:

  • content — what was decided, in one or two sentences.
  • rationale — why this over the alternatives.
  • confidence — low, medium, or high.

Optional but recommended:

  • alternatives — the options you compared against, even briefly.
  • Repo / file / commit context (the CLI and MCP server fill these in for you).

A decision is the kind of thing that, six weeks later, would otherwise be a "wait, why did we do it this way?" git-blame archaeology session.

kleio decide \
  --content "Use Postgres pgvector for embeddings" \
  --rationale "Already in our stack, eliminates a second database, perf good enough at our scale" \
  --confidence high \
  --alternatives "Pinecone (extra service), Qdrant (less ops familiarity)"

(Inside an editor with MCP, your agent calls kleio_decide directly when you commit to a direction in chat.)

Checkpoints​

A checkpoint records what shipped, after a meaningful slice is done. Not every commit. Not every line. A slice.

Required:

  • content — one or two sentences describing what was implemented.
  • slice_category — the kind of work (e.g. feature, refactor, fix).
  • slice_status — e.g. complete, partial.
  • validation_status — how the slice was verified (tests, manual check, none).

Optional:

  • caveats — known rough edges.
  • deferred — what was intentionally not done in this slice.
  • backlog_item_id — link to a backlog item (UUID or KL-N) the checkpoint closes. High-confidence semantic links between checkpoints and open backlog items can auto-close the item.

Why this is different from a git commit: see Checkpoints vs. git commits.

Work-item captures​

The "I noticed something" path. A capture flags discovered work so it doesn't get lost between this PR and the next one.

Minimum:

  • content — what the work is, in user-readable form.

Strongly recommended:

  • File / line / repo context (the CLI fills these in from your cwd; the MCP server has access to the editor's open buffer).
  • Tags or category if you have a taxonomy (tech-debt, bug, perf, etc.).
kleio capture "auth middleware is duplicated between webhook and API routes" \
  --file api/internal/middleware/auth.go --line 42 --tag tech-debt

Captures with signal_type=work_item are the only ones that synthesize into backlog items (today). Other signal types — PR reviews, CI failures, security alerts — are stored and queryable but do not yet auto-create backlog items. That gap is on the roadmap; see the org README's status section.

Backlog items​

Backlog items are derived, not captured. The synthesis pipeline (see Capture pipeline) consolidates related work-item captures into a single backlog item, deduplicating against existing items semantically. Each backlog item carries:

  • A short ID like KL-42 for human reference.
  • An Eisenhower urgency × importance classification (this replaces the older single "priority" field).
  • Provenance: which captures fed into it.
  • Optional links to the commits, PRs, decisions, or checkpoints it was derived from.

You triage backlog items via the web app, the CLI (kleio backlog list, kleio backlog prioritize), or the MCP tools.

So what?​

The mental model is:

  • Decisions explain the future.
  • Checkpoints document the past.
  • Work-item captures prevent the present from leaking.

Everything else Kleio does — dedup, synthesis, RAG via kleio_ask, provenance trails — sits on top of these three primitives plus the automatically-ingested git / PR signals.

Next: Checkpoints vs. git commits.