with one click
arc-reflecting
// Use when user requests /reflect, after 5+ diary entries accumulated, or when asked to summarize preferences from past sessions
// Use when user requests /reflect, after 5+ diary entries accumulated, or when asked to summarize preferences from past sessions
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | arc-reflecting |
| description | Use when user requests /reflect, after 5+ diary entries accumulated, or when asked to summarize preferences from past sessions |
Analyze multiple diary entries to identify recurring patterns. Save insights to ~/.arcforge/diaryed/ for user review.
| Task | Command |
|---|---|
| Determine strategy | node "${SKILL_ROOT}/scripts/reflect.js" strategy --project {project} |
| Scan diaries | node "${SKILL_ROOT}/scripts/reflect.js" scan --project {p} --strategy {s} |
| Update log | node "${SKILL_ROOT}/scripts/reflect.js" update-log --project {p} --diaries "{f}" --reflection "{id}" |
| Pattern threshold | 3+ occurrences = Pattern, 1-2 = Observation |
| Rule violations | Check CLAUDE.md first, report violations with evidence |
| Save instinct | node "${SKILL_ROOT}/scripts/reflect.js" save-instinct --project {p} --id {id} --trigger "..." --action "..." [--domain D] [--evidence "..."] [--evidence-count N] |
| Strategy modes | unprocessed (5+ new) | project_focused (5+ total) | recent_window (fallback) |
Node.js utilities handle diary scanning and processed.log management.
Set SKILL_ROOT from skill loader header (# SKILL_ROOT: ...):
: "${SKILL_ROOT:=${ARCFORGE_ROOT:-}/skills/arc-reflecting}"
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
Determine strategy (auto-detect):
node "${SKILL_ROOT}/scripts/reflect.js" strategy --project {project}
# Returns: unprocessed | project_focused | recent_window
Scan for diaries:
node "${SKILL_ROOT}/scripts/reflect.js" scan \
--project {project} \
--strategy unprocessed
# Returns: List of unprocessed diary file paths
Update processed.log after reflection:
node "${SKILL_ROOT}/scripts/reflect.js" update-log \
--project {project} \
--diaries "diary-1.md,diary-2.md,diary-3.md" \
--reflection "2026-01-reflection-2.md"
For large diary sets, use the diary-analyzer subagent (see diary-analyzer.md) to read diaries in an isolated context without polluting the main conversation.
Integration with instincts:
/reflect → ~/.arcforge/diaryed/ (reflections) + instincts saved via save-instinct/recall → retrieves instincts and learned patternsCore principle: Patterns must appear 3+ times across diary entries to be considered "Pattern". 1-2 occurrences are labeled "Observation".
/reflect~/.arcforge/diaryed/
├── global/ # Cross-project patterns
│ ├── processed.log # Tracks which diaries were processed
│ └── prefers-explicit-errors.md
└── {project}/ # Project-specific patterns
├── processed.log # Per-project tracking (no cross-pollution)
└── architecture-decisions.md
processed.log format:
# processed.log for {project}
# Format: diary_filename | processed_date | reflection_filename
diary-abc123.md | 2025-01-24 | 2025-01-reflection-1.md
diary-def456.md | 2025-01-24 | 2025-01-reflection-1.md
NOT auto-loaded by Claude. User must manually review.
Before reading diaries, determine the optimal filtering strategy:
Strategy Selection Algorithm:
┌─────────────────────────────────────────────────────────────┐
│ 1. Check processed.log for project │
│ 2. Count unprocessed diaries │
│ │
│ IF unprocessed >= 5: │
│ → Mode: "unprocessed" - analyze only new diaries │
│ ELIF current_project has 5+ total diaries: │
│ → Mode: "project_focused" - analyze project diaries │
│ ELSE: │
│ → Mode: "recent_window" - analyze recent 10 diaries │
└─────────────────────────────────────────────────────────────┘
Output the strategy header at start of reflection:
## Reflect Strategy
**Mode:** {unprocessed|project_focused|recent_window}
**Diaries analyzed:** {count}
**Reason:** {why this mode was selected}
**Projects covered:** {project} (count), ...
Search for diary files:
~/.arcforge/diaries/{project}/*/diary-*.md
Count entries. If fewer than 3:
"Found only X diary entries. Run more sessions with /diary before reflecting."
Before analyzing diaries, read the project's CLAUDE.md to:
This enables the skill to detect when diaries show user corrections for breaking existing rules.
Read each diary entry. Look for:
Observation Cross-Reference: When observations are available (~/.arcforge/observations/{project}/observations.jsonl), cross-reference diary patterns with tool call data for stronger evidence. Tool usage sequences that match diary-reported techniques provide quantitative backing for patterns. For example, if a diary mentions "always grep before editing", check observations for Grep→Read→Edit sequences to confirm frequency.
Pattern threshold (3+ occurrences): A pattern MUST appear in 3+ diary entries to be labeled "Pattern".
Observation (1-2 occurrences): Noted but not promoted to pattern status.
For each potential pattern, track:
For rule violations, track:
Use this structure (with strategy header from step 1):
## Reflect Strategy
**Mode:** {mode}
**Diaries analyzed:** {count}
**Reason:** {reason}
**Projects covered:** {list}
---
## Rule Violations Detected (PRIORITY)
### Violation: {rule-name}
**Existing Rule:** "{quoted from CLAUDE.md}"
**Violation Pattern:** User corrected Claude in N sessions
**Evidence:**
- [YYYY-MM-DD] diary-{id}: "{correction quote}"
- [YYYY-MM-DD] diary-{id}: "{correction quote}"
**Suggested Action:** Strengthen rule in CLAUDE.md (user decides)
---
## Patterns Identified (3+ occurrences)
### Pattern: {pattern-name}
**Occurrences:** N sessions
**Evidence:**
- [YYYY-MM-DD] Session {id}: {how it appeared}
- [YYYY-MM-DD] Session {id}: {how it appeared}
**Implication:** {what this suggests}
**Confidence:** High/Medium
---
## Observations (1-2 occurrences)
- {observation}: seen in {N} session(s)
Note: Rule violations appear FIRST (priority) before patterns.
Reflections and instincts are auto-saved. Inform user of what was saved.
"I found these patterns/violations across X diary entries. Saving reflection and instincts."
For rule violations, additionally inform:
"These rule violations suggest strengthening CLAUDE.md. Would you like to update those rules?"
~/.arcforge/diaryed/{project}/ or ~/.arcforge/diaryed/global/ existsYYYY-MM-reflection-N.md)diary-abc123.md | 2025-01-24 | 2025-01-reflection-1.md
node "${SKILL_ROOT}/scripts/reflect.js" save-instinct \
--project {project} \
--id {pattern-name} \
--trigger "{when this applies}" \
--action "{what to do}" \
--domain {category} \
--evidence "{source diary references}" \
--evidence-count {N}
Every pattern MUST cite specific diary entries as evidence. No patterns based on general assumptions.
Reflections and instincts are auto-saved. Inform user of what was saved.
Insights are observations, not rules. User decides how to act on them.
Diaryed patterns are for reflection. If user wants auto-loading, redirect to /recall.
Wrong: "You mentioned preferring TypeScript twice" → calling it a Pattern Right: 1-2 occurrences = Observation, 3+ occurrences = Pattern
Wrong: "You seem to prefer X" Right: "Based on sessions from Jan 15 and Jan 20, you consistently chose X"
Wrong: Putting reusable techniques here Right: Observations go to diaryed; techniques go to learned
Wrong: "You should always use TypeScript" Right: "Observed: Chose TypeScript in 4/5 new projects"
Wrong: Saving reflection but not updating processed.log Right: Always append processed diary filenames to log after save
Wrong: Automatically updating CLAUDE.md when violations found Right: Report violations and ask user if they want to update rules
Wrong: Starting reflection without showing the filtering strategy Right: Always output strategy header (Mode, Diaries, Reason, Projects)
## Decisions Made
- Chose PostgreSQL for JSON support
- Used connection pooling
## Challenges & Solutions
- **Challenge**: User corrected "Added with AI assistance" in commit
- **Solution**: Removed AI attribution
- **Generalizable?**: Yes
## User Preferences Observed
- Prefers explicit error handling
- Likes PostgreSQL for complex queries
## Decisions Made
- Selected PostgreSQL again for new service
## Challenges & Solutions
- **Challenge**: User said "Don't mention Claude in PR description"
- **Solution**: Removed AI mention
- **Generalizable?**: Yes
## Reflect Strategy
**Mode:** unprocessed
**Diaries analyzed:** 5
**Reason:** 5 new diaries since last reflection (2025-01-10)
**Projects covered:** my-api-project (5)
---
## Rule Violations Detected (PRIORITY)
### Violation: AI Attribution
**Existing Rule:** "Never add AI attribution to commits" (from CLAUDE.md)
**Violation Pattern:** User corrected Claude in 2 sessions
**Evidence:**
- [2025-01-15] diary-abc123: "User corrected 'Added with AI assistance' in commit"
- [2025-01-22] diary-ghi789: "User said 'Don't mention Claude in PR description'"
**Suggested Action:** Strengthen rule in CLAUDE.md to include PR descriptions
---
## Patterns Identified (3+ occurrences)
### Pattern: prefers-postgresql
**Occurrences:** 3 sessions
**Evidence:**
- [2025-01-15] Session abc123: Chose PostgreSQL for JSON support
- [2025-01-18] Session def456: Expressed preference for PostgreSQL complex queries
- [2025-01-20] Session ghi789: Selected PostgreSQL for new service
**Implication:** PostgreSQL is the preferred default database
**Confidence:** High
---
## Observations (1-2 occurrences)
- Prefers connection pooling: seen in 1 session
- Prefers explicit error handling: seen in 1 session