Actions

A logbook that only gets queried is a reference. A logbook that drives execution is a coordination surface. Actions are the bridges from logbook state to external systems.

The pattern: logbook → query → action. A query selects entries by criteria. An action takes those entries and does something outside the logbook — creates tickets, generates documents, populates a workshop board, triggers agent runs.

Commit to tracker

Real APIs like Jira have strict schemas — a ticket requires project, issue type, summary, and often priority, assignee, story points, and more. You can't save a half-formed ticket. But shaping work is inherently partial: early entries might have a task name and component but no estimate, or a risk assessment but no assignee. The logbook is the permissive staging layer where partial entries are valid; fields get filled incrementally by different contributors across sessions until the entry is complete enough to commit.

The commit action validates readiness (are all target-required fields populated?), surfaces gaps (filter commit_decision=approved AND estimate=null), and creates tickets only from fully-formed entries. Each committed entry gets a ticket_id column patched back. The logbook is authoritative during shaping; after commit, the tracker is authoritative. One-way push, no sync back.

Apply to workshop surface

Export entries as Miro sticky notes, Figma cards, or any visual collaboration tool. Group by a column (tag, component, phase). Include provenance on each card (source_agent, score). The workshop surface is the next stage, not a mirror — no two-way sync.

Generate report

Export filtered entries as a formatted document — a summary for stakeholders, a handoff brief for the next team, a decision log for compliance. The report is a snapshot, not a live view. Regenerate it when the logbook changes.

Trigger agent run

Use logbook state as input to a new agent session. A retro logbook with unresolved high-severity entries triggers a skill improvement agent. A backlog logbook with unestimated entries triggers an estimation agent. The logbook is the work queue; the agent processes entries and patches results back.

Visualize

Render a filtered slice — or the whole thing — as a chart, board, timeline, or heatmap. Group ideation entries by tag in a bubble chart. Show backlog candidates on a risk-vs-effort scatter plot. Render a retro logbook as a severity heatmap across runs. The visualization is a view on top of the logbook, not a copy — regenerate it when the data changes.

---

Principles for actions

Each action is specific to one logbook

The ideation logbook has "apply to Miro." The backlog logbook has "commit to Jira." Do not build a universal action dispatcher — that's the unified-substrate anti-pattern applied to execution.

Always include a dry-run mode

Before creating 50 Jira tickets, print what would be created, with counts and warnings for missing fields. The cost of undoing a bad batch export is high.

Log what they did

Every commit, apply, or export writes a row to an action log: timestamp, action type, filter used, count of entries acted on, target URL or ID. This is how you answer "when did we last push to Jira and which entries were included?"

Avoid bidirectional sync

The logbook pushes to external systems; patch back identifiers (ticket_id, export URL) or action metadata only when later queries need them. Do not mirror ongoing target-system edits back into the logbook. If a Jira ticket gets updated after commit, that update lives in Jira — the logbook's job ended at commit. Maintaining two editable copies creates the "second place to update" anti-pattern.

---

Governance

Ownership

Every logbook has exactly one owner: a person or role responsible for schema changes, conflict resolution, and sunset decisions. Contributors can append and patch rows; the owner decides when the schema evolves or the logbook closes. If no one owns it, no one will maintain it.

Access and visibility

Decide at creation who can write, who can read, and whether the logbook is visible outside the immediate team. For agent-written logbooks, this also means deciding which agents have append access and which have read-only query access. The default should be narrower than you think — widen it when someone asks.

Conflict resolution

Two contributors patching the same row at the same time is inevitable. For flat files, the rule is last-write-wins with git history as the audit trail. For spreadsheets, the rule is whatever the platform provides. For SQLite, use transactions. Pick an explicit rule and tell contributors what it is, rather than hoping conflicts don't happen.

Provenance

Decide at creation whether the logbook needs to track who wrote what and when. A short-lived ideation logbook might only need source_agent. A retro logbook spanning months needs timestamps. A compliance-sensitive logbook needs full created_by, created_at, updated_by, updated_at. Don't mandate provenance columns by default — add the ones the logbook's queries will actually use.

Retention and sunset

Every logbook should have an expected lifetime: one sprint, one quarter, indefinite. When the lifetime expires, the owner reviews it. The options are: archive (move to cold storage, stop querying), collapse (extract summary into a document, delete the logbook), or renew (confirm it's still active, extend the window). A logbook with no sunset rule will outlive its usefulness and become a maintenance ghost.