tenbrains · design spec

Learning objectives

A persistent goal like "Stablecoins" you tag things with — a followed account, an X post, a YouTube video, a learning track. The objective becomes a lens across the whole tool: everything you gather toward a goal links to it, untagged stays general, and progress accumulates per objective instead of scattering across one-off tracks.

Draft · for team review Owner: @moeghashim Target: tenbrains 2.3.0 One feature · 4 PRs Migration v4

# set a goal, then tag what you gather toward it — across follows, posts, videos
tenbrains objective add "Stablecoins" --focus
tenbrains takeaway follow maker --objective stablecoins # I follow them to learn this
tenbrains analyze --url "https://youtu.be/…" --objective stablecoins --learn
tenbrains objective show stablecoins # every tagged account/post/track + progress

01 Motivation

Today a learning track is built from one post's concepts and stands alone — no way to say "these ten posts, two accounts, and three videos are all me working toward stablecoins."
A goal is a natural spine: it ties follow, analyze (X + YouTube), bookmark, and learn together and gives suggest/digest a direction to point at.
It's the difference between a pile of analyses and a curriculum.

02 Locked decisions

First-class & separate from bookmark tagslocked — objectives carry goal semantics (description, active/archived lifecycle, a current focus, mixed-type tagged records, progress) that a loose tag can't. Tags stay for labeling; objectives are for direction. They coexist.

Multiple objectives, one current focuslocked — pursue several goals at once; at most one is the focus. Focus is the default view/bias target and never auto-tags — tagging is always explicit, so untagged stays general.

Manual tagginglocked — attach objectives explicitly via --objective or objective link. Inferring an objective from content is out of scope.

03 Data model — migration v4

Schema is at v3 today (YouTube added none); objectives add v4. Two tables — a first-class entity plus a polymorphic many-to-many join, so a post can serve two goals and an objective can span record types.

objectives(id obj_…, slug UNIQUE, name, description, status, is_focus, …)
objective_links(objective_id → objectives, record_type, record_id)
# record_type ∈ post | account | bookmark | track · reverse index for `record get`

04 CLI surface

Manage

objective add <name> [--description <t>] [--focus] # create; derives slug
objective list [--status active|archived|all]
objective show [<slug>] # detail + tagged records + progress (defaults to focus)
objective focus <slug> | --clear
objective archive <slug>
objective link | unlink --objective <slug> <recordId> # tag an existing record

Tag at creation — `--objective <slug>` (repeatable)

analyze … --objective stablecoins # tag the post (X/thread/YouTube/text)
takeaway follow <user> --objective stablecoins # tag the account
bookmark add … --objective stablecoins # tag the bookmark's post
learn generate --objective stablecoins # track belongs to the objective

Unknown slug → structured NOT_FOUND pointing at objective add (no silent auto-create). learn inherits the objective from a tagged source post. Tagging commands add meta.objectives to the envelope.

05 Impact map

Surface	Change
Data model	`objectives` + `objective_links`; `obj_` id; migration v4.
New `objective` cmd	add / list / show / focus / archive / link / unlink.
`analyze` (X, thread, YouTube, text)	`--objective` tags the post — one flag covers every source (all route through `analyze`).
`takeaway follow`	`--objective` tags the account.
`bookmark add`	`--objective` tags the post.
`learn`	Track tagged (explicit or inherited); counts toward progress; concept order reweighted by the goal.
`record get`	Shows a record's objective tags.
`suggest` / `digest` / `search`	Bias / filter by objective (final PR).

06 Delivery — one feature, four PRs

The complete feature ships as one release (2.3.0), built as review-sized PRs. Each is independently CI-green and builds on the last; Codex opens one, hands a review prompt back to Claude for sign-off, then proceeds.

PR 1

Core. Tables (migration v4), repository, obj_ id, objective add/list/show/focus/archive, record get tags.→ create, focus, and inspect objectives

PR 2

Tagging. objective link/unlink + --objective on analyze/follow/bookmark/learn (learn inherits).→ attach records to a goal; objective show lists them

PR 3

Learn lens. Reweight track concept ordering by the objective's description (deterministic token overlap); richer progress.→ study plans aimed at the goal

PR 4

Bias. suggest ranks toward the focus; digest/search gain an --objective filter; bump to 2.3.0.→ point the whole tool at the goal

Composes with YouTube (PR #8)

Non-blocking. YouTube ships without objective-awareness; because it routes through analyze, --objective covers YouTube transcripts uniformly the moment this lands — no YouTube-specific work. The only shared file is analyze.ts (one added flag).