contextia log

contextia log manages session logs — structured records of what happened during a work session on a task. Logs use the SBAR template (Situation, Assessment, Recommendation) to ensure consistent, useful documentation of each session.

Synopsis

contextia log <subcommand> [OPTIONS]

Subcommands

log write

Write a new session log entry for an active task. If no session exists for today, a new one is created with an auto-incremented session number.

contextia log write <task-id> [OPTIONS]

Option	Short	Description
--situation <text>	-S	Situation: what was the state when the session started
--assessment <text>	-A	Assessment: what was discovered or accomplished
--recommendation <text>	-R	Recommendation: what should happen next
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json

$ contextia log write TASK-007 \
    --situation "OAuth token exchange not implemented yet" \
    --assessment "Implemented PKCE flow, tests passing for happy path" \
    --recommendation "Add error handling for expired tokens, then wire up middleware"
Written session log: .contextia/work/logs/TASK-007/session-002.md

The generated session log file:

---
task: TASK-007
session: 2
date: 2026-03-02
status: open
---

# Session 2 — 2026-03-02

## Situation

OAuth token exchange not implemented yet.

## Assessment

Implemented PKCE flow, tests passing for happy path.

## Recommendation

Add error handling for expired tokens, then wire up middleware.

log read

Read session logs for a task.

contextia log read <task-id> [OPTIONS]

Option	Short	Description
--session <n>	-n	Read a specific session number (default: latest)
--all	-a	Show all sessions for the task
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json

$ contextia log read TASK-007
Session 2 (2026-03-02) — open

  Situation:      OAuth token exchange not implemented yet.
  Assessment:     Implemented PKCE flow, tests passing for happy path.
  Recommendation: Add error handling for expired tokens, then wire up middleware.

$ contextia log read TASK-007 --all
Session 1 (2026-02-28) — closed
  Situation:      Starting OAuth implementation from scratch.
  Assessment:     Set up OAuth client config, registered app with provider.
  Recommendation: Implement token exchange flow next.

Session 2 (2026-03-02) — open
  Situation:      OAuth token exchange not implemented yet.
  Assessment:     Implemented PKCE flow, tests passing for happy path.
  Recommendation: Add error handling for expired tokens, then wire up middleware.

log close

Close the current open session log for a task. A closed log signals that the session is finished.

contextia log close <task-id> [OPTIONS]

Option	Short	Description
--summary <text>		Optional closing summary appended to the log

$ contextia log close TASK-007
Closed session 2 for TASK-007
  status: open -> closed

$ contextia log close TASK-007 --summary "PKCE flow complete, ready for error handling"
Closed session 2 for TASK-007
  status: open -> closed
  summary: PKCE flow complete, ready for error handling

Session numbering

Sessions are auto-incremented per task. Log files are stored in a per-task directory:

.contextia/work/logs/
└── TASK-007/
    ├── session-001.md    # closed
    ├── session-002.md    # closed
    └── session-003.md    # open (current)

Only one session per task can be open at a time. Writing a new log entry when a session is already open appends to the existing session. Writing when no session is open (or the previous one is closed) creates a new session file.

SBAR template

Contextia uses SBAR (Situation, Assessment, Recommendation) as the session log structure. This format, borrowed from clinical communication, ensures that session handoffs between agents (or between an agent and a human) are structured and actionable:

Section	Purpose	Example
Situation	What was the state when the session started	”Rate limiting not implemented, SPEC-API-005 approved”
Assessment	What was discovered or accomplished	”Implemented token bucket algorithm, 95% test coverage”
Recommendation	What should happen next	”Add Redis backend for distributed rate limiting”

Examples

JSON output for scripting:

$ contextia log read TASK-007 --all --json
[
  {
    "task": "TASK-007",
    "session": 1,
    "date": "2026-02-28",
    "status": "closed",
    "situation": "Starting OAuth implementation from scratch.",
    "assessment": "Set up OAuth client config, registered app with provider.",
    "recommendation": "Implement token exchange flow next."
  },
  {
    "task": "TASK-007",
    "session": 2,
    "date": "2026-03-02",
    "status": "open",
    "situation": "OAuth token exchange not implemented yet.",
    "assessment": "Implemented PKCE flow, tests passing for happy path.",
    "recommendation": "Add error handling for expired tokens."
  }
]

Context format for agent handoff:

$ contextia log read TASK-007 --format context
[TASK-007 session:2 2026-03-02 open]
S: OAuth token exchange not implemented yet.
A: Implemented PKCE flow, tests passing for happy path.
R: Add error handling for expired tokens, then wire up middleware.

Behavior

• The write subcommand requires the task to be in active status. Writing to a created or completed task produces an error.
• The close subcommand marks the frontmatter status field as closed. It does not delete the file.
• The read subcommand works on tasks in any status, including completed.
• If a task has no session logs, log read prints “No session logs for TASK-XXX” and exits with code 0.