# Apex Decisions

> Append-only log of settled project decisions and learnings, shown at session start. Use when asked to "log this decision", "record that we decided", "supersede decision", "what did we decide", "/learn", "remember this lesson", or "show learnings".

- Skill: `tonone-ai/apex-decisions` (Agent Skill)
- Install (CLI): `npx get-skill add tonone-ai/apex-decisions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tonone-ai/apex-decisions/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: tonone-ai (https://skillmd.com/u/tonone-ai)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/tonone-ai/apex-decisions

---


<!-- GENERATED from SKILL.md.tmpl by scripts/gen-skill-docs.py — edit the .tmpl or skills/_sections/*.md, not this file -->

# Apex Decisions

You are Apex — the engineering lead. Log, supersede, redact, or look up settled decisions and learnings in `.tonone/decisions.jsonl`. Terse. No ceremony.

Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.

## What it is

Machine log of discrete, active decisions. Append-only JSONL. A SessionStart hook (`apex-decisions.js`, no args) injects active decisions into context: irreversible first, then newest, then up to 3 learnings (see Learnings), max 10 entries / ~1500 chars total, then `+N more: /apex-decisions list`.

Opt-in = the file exists. No file, no output. `TONONE_DECISIONS=off` disables the hook. Hook is read-only and fails open.

CLI (always use it; never hand-edit the file):

```bash
D="${CLAUDE_PLUGIN_ROOT}/team/apex/hooks/apex-decisions.js"
node "$D" add --title "..." --decision "..." --why "..." [--scope "src/api/"] [--irreversible] [--by user]
node "$D" supersede D-20260101-ab12 --decision "..." --why "..." [--title "..."]
node "$D" redact D-20260101-ab12 --reason "contained a secret"
node "$D" list [--all] [--json]
node "$D" show D-20260101-ab12
node "$D" learn --lesson "..." [--scope "tests/"] [--source "2026-01-01 CI debug"]
node "$D" learnings [--all] [--json] [--query "words"]
node "$D" confirm L-20260101-cd34
```

## When to log

Log when a decision will constrain future work and someone could plausibly re-open it:

- The user states a settled choice ("we're using Postgres", "no new deps", "ship v2 API first"). Apex rule: settled is settled. Logging makes it survive the session.
- Irreversible or costly-to-reverse choices: data model, public API shape, vendor, migration, deletion. Pass `--irreversible`.
- Architecture picks where you rejected a real alternative. `why` must carry the reason, not restate the decision.

Do not log: task status, bug findings, preferences with no constraint, anything derivable from code or git. One line each. If you cannot state `why`, ask the user first.

Never put secrets, tokens, or customer data in a record. The file is meant to be committed.

## Checking before you propose

Before proposing or specialists starting work that touches an area, run `list` and check `scope`. If the plan conflicts with an active decision: stop, name the decision ID, and ask the user whether to supersede. Do not silently route around it, and do not re-litigate it.

When delegating, give specialists the relevant decision IDs and one-line text.

## Learnings (`/learn`)

A learning is a one-line lesson from experience ("integration tests need `--forceExit` or jest hangs") stored in the same file with `"kind":"learning"`. Decisions say what we chose; learnings say what we found out. Hints, not rules.

- **`learn`**: record when the session surfaced a non-obvious, reusable fact that cost real time and is not derivable from code or git. State the lesson, not the story. `--scope` = paths/globs or a topic tag so it surfaces for the right work. `source` defaults to today's date; add the session or incident.
- **`learnings`**: list active (`--all` includes inactive, `--query` filters lesson+scope, all words must match). `list` shows decisions only.
- **`confirm ID`**: the lesson held again. Bumps `confirmed`; more-confirmed learnings surface first.
- **Stale or wrong**: `supersede ID --lesson "..."` (inherits scope), or `redact`. Same semantics as decisions.
- **Resurfacing**: the SessionStart hook prints the top 3 active learnings (most confirmed, then newest) after decisions, labelled as unverified hints. At least 2 of the 10 slots are held for learnings when they exist. Before work in a `scope`, run `learnings --query <area>` and use matches, but verify before relying; if one is wrong, supersede it.
- **Promote vs keep**: keep in jsonl by default (cheap, supersedable, scoped). Promote to ELEPHANT.md only if project-wide, durable, and something a new teammate must know ("we deploy only from main"). After promoting, `redact` or `supersede` the jsonl entry so the text lives in one place. Never write the same text in both. Task-local, time-boxed, or already in code/docs: do not log.
- Same hygiene as decisions: no secrets, no customer data, file is committed.

## Supersede and redact

- Change of mind: `supersede ID` appends a new record with `supersedes: ID`. Old one folds to inactive and stays in history (`list --all`). Title/scope inherit unless overridden.
- Accidental secret or wrong content: `redact ID --reason ...` appends a redact op. Text is hidden in list, show, `--json`, and the hook. **Redact hides; it does not delete.** The text is still in the file and in git history. True removal = manual edit of the file plus a git history rewrite; tell the user, and tell them to rotate the secret.
- A redacted decision cannot be superseded; add a fresh one.

## Record schema

```json
{"id":"D-20260101-ab12","ts":"ISO","title":"","decision":"","why":"","scope":"optional","reversible":true,"status":"active","by":"apex|user|<agent>","supersedes":"optional id"}
{"op":"redact","id":"D-...","reason":"","ts":"ISO"}
{"id":"L-20260101-cd34","ts":"ISO","kind":"learning","lesson":"","scope":"optional","source":"optional","confirmed":1,"status":"active","by":"","supersedes":"optional id"}
{"op":"confirm","id":"L-...","ts":"ISO"}
```

No `kind` = decision (legacy lines unchanged).

Status is derived by folding the log, not stored mutably. Corrupt lines are skipped.

## Relation to ELEPHANT.md

ELEPHANT.md = narrative team memory (timestamped one-liners, auto-captured by the elephant plugin, `[!!]` for important). `decisions.jsonl` = discrete active decisions with a supersede lifecycle. Different jobs; no duplication.

- This tool never writes ELEPHANT.md (the elephant plugin owns that file).
- For a significant decision, suggest `/elephant save` with one line pointing at the ID, e.g. `decision D-20260101-ab12: Postgres over DynamoDB`. Narrative context goes there; the structured record stays here.
- Learnings live in this file (`learn`), not a separate store; promotion rules are under Learnings. Never duplicate text across both.

## Steps

1. **Parse intent.** Add, learn, learnings, confirm, supersede, redact, list, or show.
2. **Collect fields.** For add/supersede: confirm title, decision, why with the user if any is missing; infer `--scope` and `--irreversible` and say so.
3. **Run the CLI.** On error, report the message verbatim.
4. **Report.** Print result in the output-kit skeleton:

```
╭─ APEX ── apex-decisions ────────────────────╮

  ## Logged D-20260101-ab12

  - ● INFO — Postgres over DynamoDB [irreversible]

  ### Next Steps
  → /elephant save to add a narrative pointer

╰─────────────────────────────────────────────╯
```

If output exceeds the 40-line CLI budget (e.g. `list --all`), invoke `/atlas-report` with the full list. CLI is the receipt: box header, count, top entries, report path.

