vt-c-session-journal¶
Continuously document decisions, activities, and learnings during work sessions. Auto-captures rationale for changes, design choices, and discovered knowledge for future reference. - Read - Write - Bash - Grep
Plugin: core-standards
Category: Knowledge Capture
Command: /vt-c-session-journal
session-journal Skill¶
Purpose: Continuously capture decisions, activities, and learnings during Claude Code sessions to build institutional knowledge that persists across sessions.
Overview¶
Unlike compound-docs (which captures solved problems after completion), this skill captures ongoing context including:
- Why a particular approach was chosen
- What alternatives were considered and rejected
- New learnings discovered during exploration
- Rationale for code changes
- Design decisions and their reasoning
Key difference from compound-docs: - compound-docs: Triggers AFTER "that worked" / problem solved - session-journal: Captures DURING work, not just at completion
Journal Structure¶
docs/vt-c-journal/
├── YYYY-MM/
│ ├── YYYY-MM-DD-session-summary.md # Daily summary
│ └── entries/
│ ├── YYYY-MM-DD-HHmm-decision.md # Individual entries
│ ├── YYYY-MM-DD-HHmm-learning.md
│ └── YYYY-MM-DD-HHmm-activity.md
└── index.md # Searchable index
Entry Types¶
1. Decision Entry¶
Captures choices made and their rationale.
Auto-detect triggers: - "I chose X because..." - "The reason for this approach..." - "We'll go with X instead of Y..." - "This is better than X because..." - Code changes with explanation
Template:
---
type: decision
date: YYYY-MM-DD HH:mm
context: [feature/bugfix/refactor]
impact: [high/medium/low]
tags: [relevant, tags]
---
# Decision: [Brief Title]
## Context
[What situation required a decision]
## Options Considered
1. **[Option A]** - [Brief description]
- Pros: ...
- Cons: ...
2. **[Option B]** - [Brief description]
- Pros: ...
- Cons: ...
## Decision
[Which option was chosen]
## Rationale
[Why this option was selected]
## Consequences
[Expected impact of this decision]
## Related
- Files changed: [list]
- Related decisions: [links]
2. Learning Entry¶
Captures new knowledge discovered during work.
Auto-detect triggers: - "I discovered that..." - "TIL..." / "Today I learned..." - "Interesting - [explanation]" - "I didn't know that..." - Unexpected behavior encountered
Template:
---
type: learning
date: YYYY-MM-DD HH:mm
category: [framework/api/pattern/tool/codebase]
confidence: [verified/likely/uncertain]
tags: [relevant, tags]
---
# Learning: [Brief Title]
## Discovery
[What was learned]
## Context
[How this was discovered]
## Evidence
[Code, output, or documentation that confirms this]
## Implications
[How this knowledge affects future work]
## Related
- Documentation: [links]
- Code references: [file:line]
3. Activity Entry¶
Captures significant actions and their outcomes.
Auto-detect triggers: - File modifications with explanation - Investigation results - Tool outputs with analysis - Completed subtasks
Template:
---
type: activity
date: YYYY-MM-DD HH:mm
action: [implemented/investigated/refactored/fixed/configured]
scope: [files/components affected]
tags: [relevant, tags]
---
# Activity: [Brief Title]
## What
[What was done]
## Why
[Reason for this activity]
## How
[Approach taken]
## Result
[Outcome of the activity]
## Files Changed
- [file1]: [brief description of change]
- [file2]: [brief description of change]
4. Procedure Improvement Entry¶
Captures learnings that should flow back to improve toolkit procedures (skills, agents, templates).
Auto-detect triggers: - "The toolkit should..." - "This checklist is missing..." - "The specs should have included..." - "Every project should check for..." - "This pattern keeps recurring..." - Defect found that matches a gap in toolkit skills/checklists
Template:
---
type: procedure-improvement
date: YYYY-MM-DD HH:mm
target_skill: [toolkit skill name, e.g., "pd-5-specs"]
target_file: [specific file in toolkit, if known]
severity: [high/medium/low]
category: [missing-criteria/missing-step/wrong-default/missing-check/new-pattern]
tags: [relevant, tags]
---
# Procedure Improvement: [Brief Title]
## What Went Wrong
[What defect or gap was discovered in the current workflow]
## Evidence
[Specific example from the current project -- file paths, defect counts, before/after]
## Proposed Change
[What should change in the toolkit procedure]
## Expected Impact
[How many future occurrences this would prevent]
## Target
- Toolkit skill: [skill name]
- Specific file: [path within toolkit, if known]
- Section: [which section to update, if known]
Note: Procedure improvement entries (detected by keyword matching) are stored in docs/toolkit-proposals/ for cross-project scanning. Additionally, any entry type can be routed to intake/pending/from-projects/ via the explicit routing question in Step 3.5.
Capture Protocol¶
Step 1: Detect Capture Opportunity¶
Automatic triggers (should capture without asking): - Code change with explanation in prompt - Design decision articulated - Alternative approach rejected with reason - New information discovered - Investigation completed with findings
Explicit triggers:
- /vt-c-journal command
- User says "document this" or "note this"
Step 2: Extract Context¶
From the current conversation, extract: - What - The specific decision/learning/activity - Why - The rationale or reasoning - Alternatives - What else was considered (if applicable) - Evidence - Code, output, or references that support this - Impact - What this affects going forward
Step 3: Classify Entry Type¶
| If conversation contains... | Entry type |
|---|---|
| Choice between options, "because", rationale | Decision |
| New information, "discovered", "learned" | Learning |
| Completed action, file changes, results | Activity |
| "toolkit should", "checklist missing", "every project", "keeps recurring" | Procedure Improvement |
Step 3.5: Route Entry Scope¶
After classification, determine whether this entry is project-specific or a workflow-level observation that should feed back into the toolkit.
For ALL entry types (including procedure-improvement), use AskUserQuestion:
- Question: "What scope does this entry have?"
- Options:
- Project-specific — Store as a normal journal entry only (proceed to Step 4 as-is)
- Process/framework observation — Also forward to V025 toolkit intake for framework improvement
Smart default suggestion: Pre-select "Process/framework observation" if the entry text contains any of these keywords: toolkit, every project, all projects, recurring, framework, should always, workflow, pattern, keeps happening, cross-project. Also pre-select it if Step 3 classified the entry as procedure-improvement.
Otherwise, pre-select "Project-specific".
If "Process/framework observation" is selected:
- Create the normal journal entry in the current project (Step 4 proceeds as usual)
- Additionally, create an intake proposal in V025-claude-toolkit:
TOOLKIT_ROOT="TOOLKIT_ROOT"
DATE=$(date +%Y-%m-%d)
PROJECT_NAME=$(basename "$(pwd)")
TITLE="brief-title-slug"
PROPOSAL_FILE="${TOOLKIT_ROOT}/intake/pending/from-projects/${DATE}-${PROJECT_NAME}-${TITLE}.md"
With this template:
---
type: research-finding
date: YYYY-MM-DD
source: session-journal
source_project: [current project name]
source_path: [full path to the journal entry created in Step 4]
target_skill: tbd
severity: medium
category: new-pattern
toolkit_proposal_status: proposed
tags: [journal, workflow-observation, cross-project]
---
# Proposal: [Title from journal entry]
**Source**: [journal entry path]
**Source project**: [current project name]
**Type**: workflow observation captured during project work
## Finding
[Content from the journal entry — what was observed]
## Suggestion
- [Extracted from the journal entry's implications/consequences section]
## Action
- [ ] Review
- [ ] Implement
Why this step exists: Workflow-level insights captured during project work should feed back into the toolkit's intake pipeline. Without explicit routing, they remain buried in project journals and never surface as improvement proposals.
Step 4: Create Entry¶
# Set variables
DATE=$(date +%Y-%m-%d)
TIME=$(date +%H%M)
MONTH=$(date +%Y-%m)
TYPE="decision" # or learning, activity, procedure-improvement
TITLE="brief-title-slug"
# Procedure improvement entries go to toolkit-proposals/ for cross-project scanning
if [ "$TYPE" = "procedure-improvement" ]; then
mkdir -p "docs/toolkit-proposals"
ENTRY_FILE="docs/toolkit-proposals/${DATE}-${TIME}-${TITLE}.md"
else
# Standard entries go to journal/
mkdir -p "docs/vt-c-journal/${MONTH}/entries"
ENTRY_FILE="docs/vt-c-journal/${MONTH}/entries/${DATE}-${TIME}-${TYPE}.md"
fi
Step 5: Update Daily Summary¶
Append to docs/vt-c-journal/YYYY-MM/YYYY-MM-DD-session-summary.md:
Step 6: Update Index (Weekly)¶
Update docs/vt-c-journal/index.md with new entries for searchability.
Integration with Workflow¶
With TodoWrite¶
When completing a todo item that involved decisions or learnings:
[x] Implement user authentication
→ Journal: Decision on JWT vs session cookies (docs/vt-c-journal/...)
→ Journal: Learning about Rails credentials (docs/vt-c-journal/...)
With compound-docs¶
After a problem is solved and documented: 1. compound-docs creates the solution doc 2. session-journal links to it from any related decisions/learnings
With SpecKit¶
When working on spec-driven projects: - Decisions reference spec.md requirements - Learnings note spec gaps or clarifications needed
Auto-Capture Guidelines¶
SHOULD Capture (high value)¶
- Design decisions with tradeoffs explained
- Why a particular library/approach was chosen
- Discovered undocumented behavior
- Rejected approaches and why
- Performance findings
- Security considerations
- Breaking changes and migration paths
SHOULD NOT Capture (noise)¶
- Routine file reads
- Obvious syntax fixes
- Standard tool usage without insights
- Repetitive similar changes
- Temporary debugging steps
Capture Threshold¶
Ask: "Would future-me (or a teammate) benefit from knowing this?" - If YES → Capture - If UNCERTAIN → Capture briefly - If NO → Skip
Commands¶
/vt-c-journal¶
Manually trigger journal capture for current context.
/vt-c-journal-search <query>¶
Search journal entries.
/vt-c-journal-summary¶
Show today's journal entries.
Example Session¶
Conversation:
User: Add rate limiting to the API
Claude: I'll implement rate limiting. Looking at the options:
- rack-attack gem (most popular, flexible)
- redis-throttle (simpler, Redis-based)
- Custom middleware (full control)
I'll go with rack-attack because it's well-maintained, has good
Rails integration, and supports multiple throttling strategies.
The custom middleware option would give more control but isn't
worth the maintenance overhead for our use case.
[implements rate limiting]
Auto-captured journal entry:
---
type: decision
date: 2026-01-26 14:30
context: feature
impact: medium
tags: [api, security, rate-limiting, gems]
---
# Decision: Use rack-attack for API Rate Limiting
## Context
Needed to add rate limiting to protect API endpoints from abuse.
## Options Considered
1. **rack-attack** - Popular Rack middleware for throttling
- Pros: Well-maintained, flexible, good Rails integration
- Cons: Additional dependency
2. **redis-throttle** - Simple Redis-based throttling
- Pros: Simpler setup
- Cons: Less flexible, smaller community
3. **Custom middleware** - Build our own solution
- Pros: Full control over implementation
- Cons: Maintenance overhead, reinventing the wheel
## Decision
rack-attack gem
## Rationale
- Well-maintained with active community
- Good Rails integration out of the box
- Supports multiple throttling strategies (by IP, by user, etc.)
- Custom middleware not worth maintenance overhead for this use case
## Consequences
- Added rack-attack to Gemfile
- Need to configure throttling rules in initializer
- Redis recommended for distributed rate limiting
## Related
- Files changed: Gemfile, config/initializers/rack_attack.rb
Success Criteria¶
Journal capture is successful when:
- [ ] Entry type correctly identified (decision/learning/activity/procedure-improvement)
- [ ] Rationale/reasoning captured (not just what, but why)
- [ ] Context sufficient for future understanding
- [ ] Alternatives documented (for decisions)
- [ ] Evidence included (for learnings)
- [ ] Files/scope noted (for activities)
- [ ] Entry placed in correct date folder
- [ ] Daily summary updated
Configuration¶
Enable Auto-Capture¶
In project's CLAUDE.md:
## Session Journal
- Auto-capture: enabled
- Capture threshold: medium # low/medium/high
- Journal path: docs/vt-c-journal/
Disable for Session¶
Error Handling¶
Missing context: - Ask for clarification before creating incomplete entry - "What was the main reason for choosing X over Y?"
Duplicate detection: - Check for similar recent entries - Suggest linking instead of duplicating
Large sessions: - Summarize at natural breakpoints - Create umbrella entry linking related decisions
Open Brain Capture (Optional)¶
After writing the journal entry, if the capture_thought MCP tool is available, capture the entry to Open Brain for semantic search across sessions.
When to capture: After every finalized journal entry.
How:
1. Check if capture_thought tool is available (MCP connected). If not: skip silently — no error, no warning.
2. If the journal entry content is empty or was cancelled: skip capture.
3. Call capture_thought with:
thought: "Decision: {what was decided}. Context: {why this decision was needed}. Alternatives: {what else was considered}. Project: {project name from CLAUDE.md or git remote}."
capture_thought times out or errors: log a debug message and continue. Never fail the skill.
This step is always last — it never interrupts or reorders the journal workflow.