Update Berrykuipers Claude Code Toolkit

---
name: dev-memory-update
description: Update development memory (events.jsonl) based on commit metadata and diff analysis. Automatically tracks features, fixes, refactorings, and decisions.
---

# Dev Memory Update Skill

Automatically extract and store development events from git commits into `ai_memory/events.jsonl`.

## Purpose

This skill analyzes commit metadata (message, diff, branch, timestamp) and creates structured event records that build an automated development timeline for the project.

## When to Use

### Automatic Invocation
- **Post-commit hook:** Runs automatically after every `git commit`
- **Batch mode:** Process multiple commits at once

### Manual Invocation
- When reviewing past commits to backfill memory
- When commit hook was disabled and you want to catch up
- When you want to add events for non-commit activities (meetings, decisions)

## Input Requirements

### Required
```typescript
{
  repo: string;              // Repository name (not full path)
  branch: string;            // Current git branch
  commit_hash: string;       // Git SHA (short or long form)
  commit_message: string;    // Full commit message
  commit_timestamp: string;  // ISO 8601 timestamp
}
```

### Optional
```typescript
{
  diff_summary?: string;     // Output of `git diff --stat`
  files_changed?: number;    // Count of modified files
  related_issues?: string[]; // Extracted issue numbers
  related_prs?: string[];    // Extracted PR numbers
  author?: string;           // Commit author
}
```

## Behavior

### Step 1: Initialize Memory Directory

```bash
# Ensure ai_memory/ exists
MEMORY_DIR="ai_memory"
mkdir -p "$MEMORY_DIR"

# Create .gitkeep if first time
if [ ! -f "$MEMORY_DIR/.gitkeep" ]; then
  echo "# AI Development Memory" > "$MEMORY_DIR/.gitkeep"
  echo "# Auto-generated by dev-memory-update skill" >> "$MEMORY_DIR/.gitkeep"
fi
```

### Step 2: Extract Metadata

```typescript
// Parse commit message for patterns
const parseCommitMessage = (message: string) => {
  const lines = message.split('\n');
  const subject = lines[0];
  const body = lines.slice(1).join('\n').trim();

  // Extract type from conventional commit format
  const typeMatch = subject.match(/^(feat|fix|refactor|test|docs|chore|perf|style|build|ci)(\(.+\))?:/);
  const type = typeMatch ? typeMatch[1] : null;

  // Extract issue/PR numbers
  const issueMatches = message.match(/#(\d+)/g) || [];
  const issues = issueMatches.map(m => m);

  const prMatches = message.match(/\bPR #(\d+)\b/gi) || [];
  const prs = prMatches.map(m => '#' + m.match(/\d+/)[0]);

  // Extract epic ID if present
  const epicMatch = message.match(/epic[:-]\s*([a-z0-9-]+)/i);
  const epicId = epicMatch ? epicMatch[1] : null;

  return { subject, body, type, issues, prs, epicId };
};
```

### Step 3: Infer Event Type

Map commit type to event type:

| Commit Type | Event Type | Notes |
|-------------|------------|-------|
| `feat` | `feature_implemented` | New functionality |
| `fix` | `bug_fixed` | Bug resolution |
| `refactor` | `refactor` | Code restructuring |
| `test` | `test_added` | Test coverage |
| `docs` | `docs_updated` | Documentation |
| `perf` | `feature_implemented` | Performance improvement treated as feature |
| `build`, `ci`, `chore` | No event | Skip unless significant |
| No type prefix | `feature_implemented` | Default assumption |

**Decision logic:**
```typescript
const inferEventType = (commitType: string | null, message: string): EventType => {
  if (commitType === 'feat' || commitType === 'perf') return 'feature_implemented';
  if (commitType === 'fix') return 'bug_fixed';
  if (commitType === 'refactor') return 'refactor';
  if (commitType === 'test') return 'test_added';
  if (commitType === 'docs') return 'docs_updated';

  // Check for decision keywords in message
  if (/\b(decided|chose|selected|adopted)\b/i.test(message)) {
    return 'decision';
  }

  // Check for breaking change keywords
  if (/BREAKING CHANGE|breaking:/i.test(message)) {
    return 'breaking_change';
  }

  // Default to feature
  return 'feature_implemented';
};
```

### Step 4: Generate Event ID

**Performance Note:** For large files, this implementation reads the entire file. Consider optimizing by reading backwards (using `tac` command or a reverse-reading library) to find the last event ID more efficiently:

```bash
# Alternative: Read last matching event backwards (shell example)
LAST_EVENT=$(tac ai_memory/events.jsonl 2>/dev/null | grep -m1 "\"id\":\"evt-$TODAY_DATE" | jq -r '.id')
```

```typescript
const generateEventId = (): string => {
  const date = new Date().toISOString().split('T')[0].replace(/-/g, '');

  // Read existing events to find next sequence number
  const eventsFile = 'ai_memory/events.jsonl';
  const todayPrefix = `evt-${date}`;

  let maxSeq = 0;
  if (fs.existsSync(eventsFile)) {
    const lines = fs.readFileSync(eventsFile, 'utf-8').split('\n').filter(l => l.trim());
    for (const line of lines) {
      try {
        const event = JSON.parse(line);
        if (event.id?.startsWith(todayPrefix)) {
          const seqMatch = event.id.match(/-(\d{3})$/);
          if (seqMatch) {
            maxSeq = Math.max(maxSeq, parseInt(seqMatch[1], 10));
          }
        }
      } catch (e) {
        // Skip malformed lines
      }
    }
  }

  const nextSeq = (maxSeq + 1).toString().padStart(3, '0');
  return `${todayPrefix}-${nextSeq}`;
};
```

### Step 5: Extract Open Questions and Next Steps

```typescript
const extractActions = (message: string) => {
  const openQuestions: string[] = [];
  const nextSteps: string[] = [];

  const lines = message.split('\n');

  for (const line of lines) {
    const trimmed = line.trim();

    // Look for questions
    if (trimmed.endsWith('?') && trimmed.length > 10) {
      openQuestions.push(trimmed);
    }

    // Look for TODO, FIXME, action items
    if (/^(TODO|FIXME|Next|Action|Follow-up):/i.test(trimmed)) {
      const action = trimmed.replace(/^[^:]+:\s*/, '');
      nextSteps.push(action);
    }

    // Look for bullet points that look like next steps
    if (/^[-*]\s+(Add|Create|Update|Fix|Test|Implement)/i.test(trimmed)) {
      nextSteps.push(trimmed.replace(/^[-*]\s+/, ''));
    }
  }

  return { openQuestions, nextSteps };
};
```

### Step 6: Create Event Object

```typescript
const createEvent = (input: CommitInput): DevEvent => {
  const { subject, body, type, issues, prs, epicId } = parseCommitMessage(input.commit_message);
  const eventType = inferEventType(type, input.commit_message);
  const { openQuestions, nextSteps } = extractActions(input.commit_message);

  const event: DevEvent = {
    id: generateEventId(),
    timestamp: input.commit_timestamp,
    repo: input.repo,
    branch: input.branch,
    type: eventType,
    title: subject.substring(0, 100), // Truncate if needed
    summary: body.substring(0, 500) || subject,
    commit_hash: input.commit_hash.substring(0, 7), // Short SHA
  };

  // Add optional fields only if present
  if (issues.length > 0) event.related_issues = issues;
  if (prs.length > 0) event.related_prs = prs;
  if (epicId) event.epic_id = epicId;
  if (openQuestions.length > 0) event.open_questions = openQuestions;
  if (nextSteps.length > 0) event.next_steps = nextSteps;
  if (input.files_changed) event.files_changed = input.files_changed;

  // Set confidence based on how much we could extract
  event.confidence = type && issues.length > 0 ? 'high' :
                     type ? 'medium' : 'low';

  return event;
};
```

### Step 7: Append to events.jsonl

```bash
# Write event as single-line JSON
echo "$EVENT_JSON" >> ai_memory/events.jsonl
```

**IMPORTANT:**
- No trailing comma
- No pretty-printing (single line)
- UTF-8 encoding
- Append mode (`>>` not `>`)

### Step 8: Update or Create Session

**Performance Note:** This implementation reads the entire sessions file. For better performance, consider reading backwards to find the most recent session for the current branch and day:

```bash
# Alternative: Read sessions backwards (shell example)
LAST_SESSION=$(tac ai_memory/sessions.jsonl 2>/dev/null | grep -m1 "\"branch\":\"$BRANCH\"" | jq -r 'select(.timestamp_start | startswith("'$TODAY'"))')
```

```typescript
const updateSession = (event: DevEvent, commitInput: CommitInput) => {
  const sessionFile = 'ai_memory/sessions.jsonl';
  const sessionId = `sess-${event.timestamp.split('T')[0].replace(/-/g, '')}-${event.timestamp.split('T')[1].substring(0, 6).replace(/:/g, '')}`;

  // Try to find existing session for today on this branch
  let existingSession: DevSession | null = null;
  const today = event.timestamp.split('T')[0];

  if (fs.existsSync(sessionFile)) {
    const lines = fs.readFileSync(sessionFile, 'utf-8').split('\n').filter(l => l.trim());
    for (const line of lines) {
      try {
        const session = JSON.parse(line);
        if (session.timestamp_start.startswith(today) && session.branch === event.branch) {
          existingSession = session;
          break;
        }
      } catch (e) {
        // Skip malformed lines
      }
    }
  }

  if (existingSession) {
    // Update existing session
    existingSession.timestamp_end = event.timestamp;
    existingSession.created_events.push(event.id);
    if (event.commit_hash) {
      existingSession.commits = existingSession.commits || [];
      existingSession.commits.push(event.commit_hash);
    }

    // Re-write updated session (append-only: add new version, old one ignored when reading latest)
    fs.appendFileSync(sessionFile, JSON.stringify(existingSession) + '\n', 'utf-8');
  } else {
    // Create new session
    const newSession: DevSession = {
      id: sessionId,
      timestamp_start: event.timestamp,
      timestamp_end: event.timestamp,
      repo: event.repo,
      branch: event.branch,
      agent: 'Claude Code',
      summary: `Working on ${event.title}`,
      created_events: [event.id],
      commits: event.commit_hash ? [event.commit_hash] : [],
    };

    fs.appendFileSync(sessionFile, JSON.stringify(newSession) + '\n', 'utf-8');
  }
};
```

## Example Usage

### From Post-Commit Hook

```bash
#!/bin/bash
# .claude/hooks/post-commit-memory.sh

# Extract commit info
REPO=$(basename "$(git rev-parse --show-toplevel)")
BRANCH=$(git branch --show-current)
COMMIT_HASH=$(git rev-parse HEAD)
COMMIT_MESSAGE=$(git log -1 --pretty=%B)
COMMIT_TIMESTAMP=$(git log -1 --format=%aI)
FILES_CHANGED=$(git diff-tree --no-commit-id --name-only -r HEAD | wc -l)

# Call dev-memory-update skill (Claude invokes this)
echo "→ Updating dev memory for commit ${COMMIT_HASH:0:7}..."

# Claude would execute this skill with the extracted data
```

### Manual Backfill

```bash
# Process last 10 commits
git log -10 --pretty=format:'%H|%aI|%s' | while IFS='|' read hash timestamp subject; do
  # Extract and process each commit
  echo "Processing: $subject"
done
```

## Constraints

### Max Events Per Commit

**Default:** 3 events maximum per commit

**Rationale:** Most commits should represent 1 logical change. If more than 3 events, commit is likely too large.

**Override:** Can be configured in `.claude/config.yml`:
```yaml
devMemory:
  maxEventsPerCommit: 3
```

### Skipped Commits

**Skip these commit types:**
- `chore:` - Unless significant (dependency upgrades)
- `build:` - Unless build system changes
- `ci:` - Unless CI/CD improvements
- Merge commits - Don't create events for merges
- Revert commits - Could create `bug_fixed` event with note

### Error Handling

**If memory update fails:**
1. Log warning to stderr
2. Don't block the commit
3. Continue gracefully

**Never:**
- Fail the commit because memory update failed
- Throw errors that stop the workflow
- Corrupt existing JSONL files

## Output

### Success

```json
{
  "status": "success",
  "events_created": 1,
  "event_ids": ["evt-20251210-001"],
  "session_updated": true,
  "session_id": "sess-20251210-210500"
}
```

### Skipped

```json
{
  "status": "skipped",
  "reason": "Commit type 'chore' not significant enough",
  "commit_type": "chore"
}
```

### Error

```json
{
  "status": "error",
  "error": "Failed to parse commit message",
  "graceful": true
}
```

## Integration with Workflows

### Conductor Workflow
- **After Phase 4, Step 2** (commit-with-validation)
- Post-commit hook runs automatically
- Memory updated with feature/fix details

### Manual Commit Workflow
- Hook runs on every commit
- No user intervention needed
- Silent unless errors

## Related Skills

- `commit-with-validation` - Creates the commit that triggers this skill
- `dev-memory-briefing` - Reads events created by this skill
- `project-memory` - Complementary long-term memory (MCP-based)

## Configuration

In `.claude/config.yml`:

```yaml
devMemory:
  enabled: true
  autoUpdateOnCommit: true
  maxEventsPerCommit: 3
  skipCommitTypes: ['chore', 'build', 'ci']
  confidenceThreshold: 'low'  # Include all events, even low confidence
```

## Best Practices

1. **Write descriptive commit messages** - Better messages = better memory
2. **Use conventional commit format** - Helps with type inference
3. **Link issues in commits** - Use `Fixes #123` format
4. **Mention epic in commit** - Include `epic-name` in message body
5. **Add TODO/FIXME** - Extracted as next steps automatically
6. **One logical change per commit** - Easier to categorize

## Troubleshooting

### Memory not updating?
- Check `.claude/config.yml` - ensure `devMemory.enabled: true`
- Check hook is configured in `.claude/settings.json`
- Run `ls -la .claude/hooks/post-commit-memory.sh` - ensure executable
- Check `ai_memory/events.jsonl` permissions

### Wrong event types?
- Use conventional commit prefixes: `feat:`, `fix:`, etc.
- Review event type inference logic above
- Manually edit `events.jsonl` if needed (it's just JSON)

### Events.jsonl growing too large?
- Check file size: `wc -l ai_memory/events.jsonl`
- If > 10,000 lines, consider archiving old events
- Compress: `gzip ai_memory/events-2024.jsonl`

### Duplicate events?
- Check if hook running multiple times
- Review `.claude/settings.json` PostToolUse hooks
- Remove duplicates manually (edit JSONL file)