| name | arc-journaling |
| description | Use when the user asks to journal session reflections (/arcforge:arc-journaling), when the PreCompact hook triggers, or at end of a significant work session |
Session Diary Capture
Overview
Capture session reflections as structured diary entries for the learning cycle (diary → reflect → instincts). This is for deliberate reflection and pattern extraction — NOT for session continuity. For saving/resuming work across sessions, use /arc-managing-sessions save and /arc-managing-sessions resume instead.
Quick Reference
| Task | Command |
|---|
| Get diary path | node "${SKILL_ROOT}/scripts/diary.js" path --project {p} --date {d} --session {s} |
| Save diary | node "${SKILL_ROOT}/scripts/diary.js" save --project {p} --date {d} --session {s} --content "{content}" |
| Key principle | Reflect from memory, NOT by reading files |
| Permission | NEVER auto-save - always ask first |
| Template location | See "Template" section below |
Infrastructure Commands
Node.js utilities handle file paths and directory creation. Optional but recommended.
Set SKILL_ROOT from skill loader header (# SKILL_ROOT: ...):
: "${SKILL_ROOT:=${ARCFORGE_ROOT:-}/skills/arc-journaling}"
if [ ! -d "$SKILL_ROOT" ]; then
echo "ERROR: SKILL_ROOT=$SKILL_ROOT does not exist. Set ARCFORGE_ROOT or SKILL_ROOT manually." >&2
exit 1
fi
Save diary to correct location:
node "${SKILL_ROOT}/scripts/diary.js" save \
--project {project} \
--date {YYYY-MM-DD} \
--session {sessionId} \
--content "{diary_content}"
Verify path (for debugging):
node "${SKILL_ROOT}/scripts/diary.js" path \
--project {project} \
--date {YYYY-MM-DD} \
--session {sessionId}
Core distinction:
- Diary = observations, context, decisions made (stored in session directory)
- Evolve = instinct combination (the dashboard Evolve action —
arcforge learn dashboard — combines related instincts into a successor candidate)
Storage: ~/.arcforge/diaries/{project}/{YYYY-MM-DD}/diary-{sessionId}.md
Pre-Diary Check (Noise Gate)
Before creating a diary entry, verify at least ONE of these criteria is met:
- Non-trivial decision was made (architecture, tool choice, approach)
- Challenge was solved (debugging, workaround found)
- User preference was expressed (explicit or implicit)
- Technique was discovered (new pattern, integration insight)
Auto-skip these sessions (no diary needed):
- Pure Q&A (answering questions without making changes)
- Retrying the same operation (build failures, test reruns)
- Pure exploration (reading files without decisions)
- Trivial fixes (typos, formatting, single-line changes)
This is a soft gate: Claude judges based on conversation memory. User can always override by invoking arc-journaling explicitly.
When to Use
- User invokes
/arcforge:arc-journaling
- PreCompact hook triggers (conversation getting long)
- End of significant work session
- After important design decisions
- When user says "remember this" or "note this down"
When NOT to Use
- Quick Q&A sessions (< 5 tool calls)
- Pure research without decisions
- Already captured in previous diary entry this session
- Pattern extraction needed (use arc-recalling instead)
- Fails Pre-Diary Check — unless user explicitly requests
Process
1. Reflect on Conversation (Context-First)
Review the conversation from memory. DO NOT read files to gather context.
Ask yourself:
- What decisions were made and why?
- What preferences did the user express?
- What worked well? What didn't?
- What context would help next session?
2. Fill Template Sections
Use this diary template:
# Session Diary: {project}
**Date:** {YYYY-MM-DD}
**Session ID:** {sessionId}
## Decisions Made
- [Decision]: [Rationale]
## User Preferences Observed
- [Preference observed]
## What Worked Well
- [Technique or approach that succeeded]
## Challenges & Solutions
- **Challenge**: [What went wrong]
- **Solution**: [How resolved]
- **Generalizable?**: [Yes/No - pre-flags for arc-reflecting]
## PR/Review Feedback (if any)
- [Feedback]: [Action taken]
## Context for Next Session
- [Key context to remember]
---
_Captured at {timestamp}_
3. Save to Session Directory
- Ensure session directory exists
- Write to
~/.arcforge/diaries/{project}/{date}/diary-{sessionId}.md
- Confirm save location with path
4. Offer Follow-up
After saving, briefly mention:
"Diary saved. If you noticed reusable patterns, run /arcforge:arc-reflecting to extract them."
Key Principles
Observation Over Prescription
Record what happened, not rules. Patterns that should become rules belong in arc-reflecting.
User Intent Over Implementation
Focus on WHY decisions were made, not just WHAT was done.
Minimal Effort
Keep entries focused. Don't over-document routine work.
Common Mistakes
Reading Files for Context
Wrong: Reading project files to "understand" what to write
Right: Reflect on conversation memory only
Capturing Implementation Details
Wrong: "Changed line 42 of app.js to use const"
Right: "Decided to prefer const over let for immutability"
Creating Diary for Trivial Sessions
Wrong: Diary for "fixed a typo" session
Right: Skip diary, or note "No significant reflections this session"
Duplicating Learn Content
Wrong: Same pattern in both diary and instinct
Right: Diary captures context; learn extracts reusable pattern
Not Asking Permission
Wrong: Auto-saving without confirmation
Right: Present draft, ask "Should I save this diary entry?"
Skipping the Generalizable Marker
Wrong: Leaving Generalizable? empty or omitting it
Right: Always mark solutions as Yes/No - helps arc-reflecting identify patterns
Template Variables
| Variable | Source |
|---|
{project} | CLAUDE_PROJECT_DIR or path.basename(process.cwd()) |
{YYYY-MM-DD} | Current date |
{sessionId} | CLAUDE_SESSION_ID or generated |
{timestamp} | ISO timestamp |
Output Location
~/.arcforge/diaries/{project}/{YYYY-MM-DD}/
└── diary-{sessionId}.md # Diary entry (from arc-journaling)
~/.arcforge/sessions/{project}/{YYYY-MM-DD}/
└── {sessionId}.json # Session data (auto-generated)
Diary files live under ~/.arcforge/diaries/ (not ~/.claude/sessions/)
because Claude Code v2.1.78+ blocks subprocess writes to ~/.claude/.
The Stop-hook background enricher needs to be able to write there.
Example Diary Entry
# Session Diary: my-api-project
**Date:** 2025-01-24
**Session ID:** abc123-def456
## Decisions Made
- Chose PostgreSQL over MySQL: JSON column support needed for flexible schema
- Connection pooling with PgBouncer: scalability requirement for multi-tenant
## User Preferences Observed
- Prefers explicit error handling over try-catch blocks
- Likes detailed commit messages with context
## What Worked Well
- TDD approach helped catch edge case early
- Breaking large migration into smaller steps
## Challenges & Solutions
- **Challenge**: Docker networking issues blocked local development
- **Solution**: Used host network mode instead of bridge
- **Generalizable?**: Yes - applies to any Docker-based local dev
- **Challenge**: Prisma limitation with composite keys
- **Solution**: Workaround using @@id directive with custom naming
- **Generalizable?**: No - specific to this Prisma version
## PR/Review Feedback (if any)
- "Add rollback logic to migration": Added down() method to all migration files
## Context for Next Session
- Migration is half-complete; start with users table
- Test database needs to be reset before next run
---
_Captured at 2025-01-24T15:30:00Z_