# Logbook > The project's single "what's on deck" surface β€” one command, two sections. Shows the best-practice lifecycle stages this project should adopt next (computed from repo state, via the recommendation engine) AND the durable backlog of follow-ups (ideas, deferred fixes, open questions, risks, tech debt) captured at /build and /ship so they survive /clear. Lists both, and resolves, dismisses, adds, or reviews follow-ups. Use when you want to see or act on everything outstanding. Triggers: "what's next", "next steps", "/logbook", "what's on deck", "follow-ups", "the backlog", "what did we defer", "lifecycle steps", "what should I do next". - Skill: `slamb2k/logbook` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add slamb2k/logbook` - Raw SKILL.md: https://api.skillmd.com/api/skills/slamb2k/logbook/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: slamb2k (https://skillmd.com/u/slamb2k) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/slamb2k/logbook --- # Logbook - What's On Deck When this skill is invoked, IMMEDIATELY output the banner below before doing anything else. Pick ONE tagline at random β€” vary your choice each time. CRITICAL: Reproduce the banner EXACTLY character-for-character, including the diagonal `/` glyph before the name. ```text {tagline} /$$ /$$ /$$$$$$ /$$$$$$ /$$$$$$$ /$$$$$$ /$$$$$$ /$$ /$$ /$$/| $$ /$$__ $$ /$$__ $$| $$__ $$ /$$__ $$ /$$__ $$| $$ /$$/ /$$/ | $$ | $$ \ $$| $$ \__/| $$ \ $$| $$ \ $$| $$ \ $$| $$ /$$/ /$$/ | $$ | $$ | $$| $$ /$$$$| $$$$$$$ | $$ | $$| $$ | $$| $$$$$/ /$$/ | $$ | $$ | $$| $$|_ $$| $$__ $$| $$ | $$| $$ | $$| $$ $$ /$$/ | $$ | $$ | $$| $$ \ $$| $$ \ $$| $$ | $$| $$ | $$| $$\ $$ /$$/ | $$$$$$$$| $$$$$$/| $$$$$$/| $$$$$$$/| $$$$$$/| $$$$$$/| $$ \ $$ |__/ |________/ \______/ \______/ |_______/ \______/ \______/ |__/ \__/ ``` Taglines: - 🧭 Reading the ship's log... - πŸ“– Course and remarks, all in one place. - βš“ What's on deck? - πŸ—ΊοΈ Where you are, and what you noted to circle back to. - πŸ“‹ The captain's running record. - 🚒 Best-practice heading + your own remarks. - πŸ–‹οΈ Logging it before it drifts away. - πŸ“Œ Flagging what's still outstanding. --- ## Output Formatting After the banner, show parsed input: ``` β”Œβ”€ Input ──────────────────────────────────────── β”‚ Action: {show | review | resolve | dismiss | add} β”‚ Arg: {value or "none"} └──────────────────────────────────────────────── ``` Status icons: βœ… done Β· ⏭️ skipped Β· ⚠️ degraded --- ## What this does `/logbook` is the project's single **"what's on deck"** surface. It answers the one question β€” _what should I do on this project?_ β€” that used to be split across two commands, so you no longer have to guess which to call. It shows two things, clearly separated because they're genuinely different: - **🧭 Lifecycle** β€” best-practice stages this _project_ should adopt next (brace, rig, dock/hoist, keel, envs…), **computed** fresh from repo state by the Lifecycle Recommendation Engine. Prescriptive and stateless. Because you're explicitly asking, this **bypasses the ambient anti-nag suppression** (active-cycle, cooldown, dismissal watermarks) β€” you see the full picture. - **πŸ“Œ Follow-ups** β€” what _you_ said you'd come back to (ideas, deferred fixes, open questions, risks, tech debt), **committed** to `LOGBOOK.md` (plus a sibling `LOGBOOK-ARCHIVE.md` for anything that outgrows it β€” see Notes) at the repo root and auto-captured at `/build` and `/ship` debrief so they survive `/clear`. Personal and durable. It is **read-only by default** β€” it never runs a skill or resolves an item unless you choose to. All operations go through `session-guard.cjs` subcommands (single source of truth) and degrade to a no-op on a malformed file. ## Pre-flight | Dependency | Type | Check | Required | Resolution | Detail | | ------------- | ----- | ------------------------------------------------------------------------------------------------ | -------- | ---------- | ------------------------------------------------------------------------------------ | | session-guard | skill | `ls "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/slamb2k}/hooks/session-guard.cjs"` | yes | stop | Ships with the mad-skills plugin; reinstall if missing | | git | cli | `git --version` | no | fallback | Lifecycle signature + linked-item auto-resolve degrade without git (CON-002/CON-003) | ## Parse the argument The argument selects the action (default is **show** when empty): - _(empty)_ β†’ **show** both sections - `review` β†’ **review** follow-ups (assisted cleanup) - `archive` β†’ **archive** view (lists relocated-open items with `a`-prefixed selectors, plus historical archive entries for context) - `resolve >` β†’ **resolve** follow-up n (hot file) or archive item an - `dismiss >` β†’ **dismiss** follow-up n (hot file) or archive item an - `restore a` β†’ **restore** a relocated archive item back into the hot file - `add ` β†’ **add** a manual follow-up Set `_R` once for every command below: ```bash _R="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/slamb2k}" ``` ## Actions ### show (default) Query both surfaces, then render one box: ```bash node "$_R/hooks/session-guard.cjs" lifecycle-next # 🧭 lifecycle node "$_R/hooks/session-guard.cjs" logbook-list # πŸ“Œ follow-ups ``` - `lifecycle-next` prints a `LIFECYCLE_NEXT_BEGIN` … `LIFECYCLE_NEXT_END` block; each line is `{command} β€” {why}` (with `[previously dismissed]` where relevant), or `none` when nothing applies. - `logbook-list` prints a `LOGBOOK_LIST_BEGIN` … `LOGBOOK_LIST_END` block of category headings + numbered items `N. {title} β€” {source} ({date}) [{link}]`, or `LOGBOOK_LIST_EMPTY`. Render both in a single box. **Letter** the lifecycle steps (A, B, C…) and keep the follow-up **numbers** (1, 2, 3…) so the two act-verbs never collide: ``` β”Œβ”€ Logbook Β· What's on deck ───────────────────── β”‚ β”‚ 🧭 Lifecycle β€” best-practice stages for this project β”‚ A. {command} {why} β”‚ B. {command} {why} β”‚ β”‚ πŸ“Œ Follow-ups β€” what you said you'd come back to β”‚ Deferred fixes β”‚ 1. {title} {source} Β· {date} β”‚ Tech debt β”‚ 2. {title} {source} Β· {date} πŸ”— {link} β”‚ β”‚ act: resolve Β· dismiss Β· add Β· review Β· set up β”‚ └───────────────────────────────────────────────── ``` Empty-state rules (never fabricate): - Lifecycle `none` β†’ show `βœ… fully caught up β€” no lifecycle steps apply`. - `LOGBOOK_LIST_EMPTY` β†’ show `β€” no open follow-ups`. - **Both** empty β†’ collapse to a single line: `βœ… All clear β€” nothing on deck.` and stop (no verbs footer). ### set up \ (act on a lifecycle step) Only when the user picks one (or asks). Running a lifecycle step just invokes that skill (e.g. _set up A_ β†’ invoke `/keel`). **Never** run one without the user choosing it β€” every lifecycle transition is user-consented. If you want to prompt, use `AskUserQuestion` with each listed command plus _Not now_. ### review (assisted follow-up cleanup) ```bash node "$_R/hooks/session-guard.cjs" logbook-review ``` Two tracks: 1. **Deterministic** β€” linked follow-ups whose link is satisfied (`task#`, `spec:`, `rec:`, `pr#`/`commit:`) auto-resolve **silently**; a `LOGBOOK_AUTORESOLVED [...]` line means they were already handled. 2. **Assisted** β€” free-text items that look done or stale print in a `LOGBOOK_REVIEW_BEGIN` … `LOGBOOK_REVIEW_END` block as `N. {title} β€” {reason}` (`LOGBOOK_REVIEW_EMPTY` = nothing to review). Assisted candidates may mix plain hot-file items (`N`) with archive-resident relocated items (`aN`) in the same block β€” distinguishable by a `(relocated)` suffix on the reason string. Resolving an `aN` candidate (`logbook-resolve aN`) follows the same user-confirmation discipline as any hot-file candidate; it becomes ordinary archive history, it does not restore the item to the hot file (see `### restore` for that). For the assisted candidates you **MUST get user confirmation before resolving anything** (never silently drop a free-text idea). Present them via `AskUserQuestion` (multi-select + a "keep all" escape); for each confirmed item run `logbook-resolve `. Anything not confirmed stays open. **Task-linked items (`task#`):** `logbook-review` runs as a plain Node process and can't see harness task state, so it does not auto-resolve `task#` links. After it, scan the `logbook-list` output for items annotated `[task#]`; for each, call `TaskGet ` β€” if the task is `completed`, resolve it silently: `node "$_R/hooks/session-guard.cjs" logbook-resolve `. ### archive ```bash node "$_R/hooks/session-guard.cjs" logbook-archive ``` Prints a `LOGBOOK_ARCHIVE_BEGIN` … `LOGBOOK_ARCHIVE_END` block: a numbered `a1, a2, …` list of still-open items that relocated off the hot file when it hit cap β€” actionable via `resolve a` Β· `dismiss a` Β· `restore a` β€” followed by a `-- history (not actionable) --` block of resolved/dismissed archive entries shown for context only, with no action affordance beyond display. `LOGBOOK_ARCHIVE_EMPTY` when nothing has ever relocated. This is read only on demand β€” never on the hot path `/logbook`'s default `show` output touches (see Notes). ### resolve / dismiss ```bash node "$_R/hooks/session-guard.cjs" logbook-resolve > # done node "$_R/hooks/session-guard.cjs" logbook-dismiss > # not done, not wanted ``` For a plain ``, both move the follow-up to the Archive section and drop it from the open list/counts. An `a`-prefixed selector (e.g. `a3`) targets `LOGBOOK-ARCHIVE.md`'s still-open (relocated) items instead of the hot file; resolving/dismissing one does **not** move it back to `LOGBOOK.md` β€” it becomes ordinary resolved/dismissed history within the archive file itself. Confirm the archived title either way. ### restore ```bash node "$_R/hooks/session-guard.cjs" logbook-restore a ``` Moves a still-open archive item back into `LOGBOOK.md`, clearing its `relocated:` marker β€” it's an ordinary open hot-file item again. If this pushes the hot file back over cap (40 open items), the system immediately relocates whatever is now lowest-priority/oldest in the hot file, the same victim-selection rule as capture-time relocation. Report both the restore and any resulting relocation to the user β€” never silent. ### add Preview first β€” a manual add is itself always interactive and can breach cap just like an auto-capture: ```bash node "$_R/hooks/session-guard.cjs" logbook-capture-preview '[{"title":"","category":"","source":"manual","date":""}]' ``` If `would_relocate` is non-empty, present the candidate(s) via `AskUserQuestion` β€” same per-item choice pattern as `review`. Address each candidate by its title text, not the preview list's ordinal β€” the preview numbers candidates in victim-selection order (lowest priority, then oldest date), which does not match `logbook-resolve`/`logbook-dismiss`'s plain-number selector (hot-file display order); the title is matched by substring regardless of ordering, so it's the only selector guaranteed to hit the right item. Options per candidate: - **"Resolve now"** β†’ `node "$_R/hooks/session-guard.cjs" logbook-resolve ""` - **"Dismiss"** β†’ `node "$_R/hooks/session-guard.cjs" logbook-dismiss "<title>"` - **"Leave it"** β†’ no action; it relocates when the real add runs next. ```bash node "$_R/hooks/session-guard.cjs" logbook-add "<text>" --category <ideas|fixes|questions|risks|debt> --link <link> ``` `--category` (default `ideas`) and `--link` are optional. Source is `manual`, date is today. Confirm the added item β€” and if the add itself relocated another item to make room (the `Relocated to archive (cap reached): [...]` line), mention that relocation to the user too. Never silent. ## Notes - **Two sections, one glance β€” on purpose.** Lifecycle is _what a good repo does_ (computed, prescriptive); follow-ups are _what you said you'd do_ (committed, personal). Same "what now?" moment, different sources β€” the split is in the output, not in which command you call. - The follow-ups half is **distinct from tasks**: an item may link to a `task#<id>` (and auto-resolve when that task completes), but the logbook is the durable backlog, not a task queue. Promote an item to active work with `TaskCreate`; don't duplicate. - **Ambient nudges stay separate from this pull.** The Session Guard still surfaces the single causal/drift lifecycle offer mid-work, and a passive cold-start hint (`πŸ“Œ N open follow-ups`) on a genuine launch/reconnect β€” never on `/clear`. `/logbook` is the on-demand, full-picture counterpart. - `LOGBOOK.md` is committed and hand-editable. Keep the `- [ ]` checkbox shape and the category headings; the module normalizes the rest on the next write. - **Auto-migration.** Earlier versions named this file `LOG.md` / `FOLLOWUPS.md`. The module reads any legacy file and merges its items in (deduped), so a rename never orphans a backlog. The first write in a project (a capture, `resolve`, or `add`) consolidates everything into `LOGBOOK.md` and removes the legacy files β€” a visible git change. Nothing is lost across the rename. - **LOGBOOK-ARCHIVE.md** is a second, uncapped, git-tracked sibling file that overflow relocates to β€” never deletes or truncates β€” once the hot file's open-item cap or its own resolved/dismissed history window fills up. It's read only on demand (`/logbook archive`, `/logbook review`), never on the hot path; `/logbook`'s default (no-argument) output stays byte-for-byte the same as before this file existed.