tonone-ai/tonone / bundle/engineering-team/skills/apex-decisions
apex-decisions
VerifiedAppend-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".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.5 KB |
SKILL.md
View on GitHub---
name: apex-decisions
description: 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".
allowed-tools: Bash, Read
version: 0.1.0
author: tonone-ai <hello@tonone.ai>
license: MIT
compatibility: Designed for Claude Code
tags: [engineering, decisions, learnings, memory]
---
<!-- 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |