SESSION: Session Capture Workflow

Summary

After capturing the P16g audit plan via tmux yank → tee, reviewed the raw output and identified workflow improvements for rapid learning capture. Two plans were generated in this session: first to clean up the raw session file, then to install the capture-session function into the actual system (dots-quantum).

Workflow Feedback Plan

Claude’s Feedback

=== What’s Good (Keep Doing This)

  1. tmux yank → tee to file — instant capture of plan output. Zero friction.

  2. Immediate appendix with CLI exercises — learning captured at the moment of discovery, not hours later.

  3. Testing commands on the file itself — meta-learning (using find | awk to read the file you’re writing about find | awk).

  4. Renamed file for context — SESSION-2026-04-06.adoc → SESSION-refactor-thinkpad-p16-project-doc-2026-04-06.adoc.

=== What to Improve

  1. Start with an AsciiDoc header — raw paste without a header means Antora can’t render it properly

  2. Wrap plans in sidebar blocks — **** delimiters for clean rendering

  3. Fence code blocks — [source,bash] + ---- for every command

  4. Fix typos before committing — "Appendex", "commad", doubled words

  5. Antora nav requires explicit xrefs — pages don’t auto-appear in sidebar navigation

System Implementation Plan

Install capture-session to dots-quantum

=== Session File Inventory vs Nav

3 of 8 session files were missing from nav.adoc. Antora does NOT auto-include pages — every file needs an explicit xref.

=== capture-session Function

Installed to dots-quantum/shell/.config/shell/domus-captures.sh and sourced in .zshrc.

# Usage:
capture-session "slug-name"                      # Empty template
echo "content" | capture-session "slug-name"     # Wraps stdin in sidebar
tmux save-buffer - | capture-session "slug"      # Capture tmux buffer

The function auto-generates a proper AsciiDoc header with :revdate:, creates sections (Summary, Plan, Commands Learned, Workflow Notes), and reminds you to add the xref to nav.adoc.

=== Helper Aliases

alias sessions='cd .../pages/sessions'     # Quick nav
alias lsessions='ls -lt .../SESSION-*.adoc | head -20'  # List by date

Key Lesson

Antora does not auto-include pages in navigation. Every session file needs an explicit xref entry in nav.adoc. The capture-session function reminds you of this on every invocation.

Related