Actions

An action is the next concrete thing to do on a project. Cuaderno treats actions as cheap by default: the normal form is a single bullet on the project map, not a note you have to create and maintain. You only give an action its own note when it grows into real investigation. All verbs live under cdno action.

Add a next action

cdno action add --project surrogate-model --title "Profile the assembly step" --energy medium

This appends a checkbox bullet to the project’s next-actions list, tagged with its energy. That’s usually all an action ever is.

List open actions

cdno action list --project surrogate-model

Bullets that have been promoted to notes show their status (active / blocked / completed / dropped) inline. --json gives the structured list.

Promote an action to a manifest note

When an action becomes an investigation that spans days and produces evidence, promote it. This rewrites the bullet as a wikilink and scaffolds an action note (with status, energy, criteria, links). The match is a case-insensitive substring of the bullet text; energy is inherited:

cdno action promote --project surrogate-model --query "profile the assembly"

You can also create an action already promoted by passing --note to add:

cdno action add --project surrogate-model \
                --title "Characterise sample efficiency across mesh sizes" \
                --energy deep --note

Start an action

Starting is optional — nothing forces you to declare it — but it is what makes cdno now able to answer “what am I in the middle of?”, which matters most on the days you come back from an interruption and cannot remember:

cdno action start --project surrogate-model --query "assembly step"

This logs started [[surrogate-model]] — Profile the assembly step (medium) to today’s journal. What gets written is the resolved bullet text, not your query, so the later completion logs matching text and the focus clears by itself.

For work that is on no map yet — the fix you noticed, the errand in front of you — --unplanned adds the bullet and starts it in one go:

cdno action start --project surrogate-model --unplanned \
    --title "Chase the licence renewal" --energy light

That is deliberately a separate flag rather than a fallback when --query matches nothing. A fallback would turn every typo into a new action, silently.

Promoting an action between starting it and closing it is fine: promotion rewrites the bullet, and cdno now follows it to the new note, keeping the original start time.

Pause, switch and resume

Only one action is in focus at a time, so starting a second while the first is open is refused, with the command that does what you meant:

$ cdno action start --project surrogate-model --query "feature set B"
Error: Profile the assembly step is already in focus on surrogate-model (since 09:30).
To move on to this instead: cdno action switch --project surrogate-model --query 'feature set B'
Or complete or pause it first.

There are three ways to leave an action without finishing it, and they say different things:

# Stopping for now; leave yourself a note on where you were.
cdno action pause --next 'pick up at the profiler output' --reason "meeting"

# Moving to something else right now; pauses the open one and starts the new one together.
cdno action switch --project surrogate-model --query "feature set B" \
    --next 'profiler output half read'

# Coming back, later today or after a night's sleep.
cdno action resume

resume prints the next: you left, and brings the action back into focus as of now. Unlike drop, a pause does not close the bullet: it stays on the map and you can still complete it later. switch is a pause immediately followed by a start, and shows in the log as exactly that. In a terminal, pause and switch ask once where to pick up; press Enter to skip.

A start left open overnight is still your focus in the morning (cdno now says since Saturday 14:05). cdno action resume makes it today’s; otherwise it lapses after a day. See Focus for the idea and action for every flag.

Two open bullets with identical text cannot be told apart by a substring query, so neither can be closed until one is edited. This is not specific to starting; action add twice does the same.

Complete an action

Completing matches a bullet by substring, ticks it off, and logs it to today’s journal. If the action had a manifest note, that note is archived to actions/_done/<year>/ and becomes append-only:

cdno action complete --project surrogate-model --query "feature set B"

Drop an action

Not everything on the list gets done. When an action is superseded, abandoned or reprioritised, drop it rather than completing it:

cdno action drop --project surrogate-model --query "demo proposal" \
    --reason "superseded by the demo-planning action"

This matches and archives exactly like complete, but the note is stamped status: dropped with no completion date, and the journal records action dropped on … instead of action done on ….

The distinction matters more than it looks. The daily log is what the weekly review, the monthly scan and every later verdict read back from — so completing work that was never performed leaves your own vault asserting something untrue, and the only repair is a correction line written by hand. A dropped action also stays out of the completed-actions views, because it carries no completion date.

--reason is optional and worth giving. “Superseded by X” and “no longer wanted” are different facts, and only one of them tells you to go looking for the replacement.

Inline vs. manifest — when to promote

Keeping the default cheap is deliberate — it means capturing the next step never costs more than a sentence. See The Research Logbook Method for the rationale.

Next: Commitments and deadlines.