git:20260226.c78f2f5 to git:20260401.6be22af

---

name: session-chronicle

description: Session log provenance tracking. TRIGGERS - who created, trace origin, session archaeology, ADR reference.

allowed-tools: Read, Grep, Glob, Bash, AskUserQuestion

---

# Session Chronicle

Excavate Claude Code session logs to capture **complete provenance** for research findings, ADR decisions, and code contributions. Traces UUID chains across multiple auto-compacted sessions.

**CRITICAL PRINCIPLE**: Registry entries must be **self-contained**. Record ALL session UUIDs (main + subagent) at commit time. Future maintainers should not need to run archaeology to understand provenance.

**S3 Artifact Sharing**: Artifacts can be uploaded to S3 for team access. See [S3 Sharing ADR](/docs/adr/2026-01-02-session-chronicle-s3-sharing.md).

## When to Use This Skill

- User asks "who created this?" or "where did this come from?"

- User says "document this finding" with full session context

- ADR or research finding needs provenance tracking

- Git commit needs session UUID references

- Tracing edits across auto-compacted sessions

- **Creating a registry entry for a research session**

---

## File Ownership Model

| Directory | Committed? | Purpose |

| ----------------------------------------- | ---------- | ---------------------------------------- |

| `findings/registry.jsonl` | YES | Master index (small, append-only NDJSON) |

| `findings/sessions/<id>/iterations.jsonl` | YES | Iteration records (small, append-only) |

| `outputs/research_sessions/<id>/` | NO | Research artifacts (large, gitignored) |

| `tmp/` | NO | Temporary archives before S3 upload |

| S3 `eonlabs-findings/sessions/<id>/` | N/A | Permanent team-shared archive |

**Key Principle**: Only `findings/` is committed. Research artifacts go to gitignored `outputs/` and S3.

---

## Part 0: Preflight Check

Verify session storage, find project sessions, and check required tools (jq, brotli, aws, op).

**Full scripts**: [Preflight Scripts](./references/preflight-scripts.md)

Summary of steps:

1. **Verify Session Storage** - Confirm `~/.claude/projects/` exists

2. **Find Current Project Sessions** - Encode CWD path, enumerate main + subagent `.jsonl` files

3. **Verify Required Tools** - Check `jq`, `brotli`, `aws`, `op` are installed

---

## Part 1: AskUserQuestion Flows

### Flow A: Identify Target for Provenance

When the skill is triggered, first identify what the user wants to trace:

```

AskUserQuestion:

question: "What do you want to trace provenance for?"

header: "Target"

multiSelect: false

options:

- label: "Research finding/session"

description: "Document a research session with full session context for reproducibility"

- label: "Specific code/feature"

description: "Trace who created a specific function, feature, or code block"

- label: "Configuration/decision"

description: "Trace when and why a configuration or architectural decision was made"

- label: "Custom search"

description: "Search session logs for specific keywords or patterns"

```

### Flow B: Confirm GitHub Attribution

**CRITICAL**: Every registry entry MUST have GitHub username attribution.

```

AskUserQuestion:

question: "Who should be attributed as the creator?"

header: "Attribution"

multiSelect: false

options:

- label: "Use git config user (Recommended)"

description: "Attribute to $(git config user.name) / $(git config user.email)"

- label: "Specify GitHub username"

description: "I'll provide the GitHub username manually"

- label: "Team attribution"

description: "Multiple contributors - list all GitHub usernames"

```

### Flow C: Confirm Session Scope

**CRITICAL**: Default to ALL sessions. Registry must be self-contained.

```

AskUserQuestion:

question: "Which sessions should be recorded in the registry?"

header: "Sessions"

multiSelect: false

options:

- label: "ALL sessions (main + subagent) (Recommended)"

description: "Record every session file - complete provenance for future maintainers"

- label: "Main sessions only"

description: "Exclude agent-* subagent sessions (loses context)"

- label: "Manual selection"

description: "I'll specify which sessions to include"

```

**IMPORTANT**: Always default to recording ALL sessions. Subagent sessions (`agent-*`)

contain critical context from Explore, Plan, and specialized agents. Omitting them

forces future maintainers to re-run archaeology.

### Flow D: Preview Session Contexts Array

Before writing, show the user the full `session_contexts` array, then confirm:

```

AskUserQuestion:

question: "Review the session_contexts array that will be recorded:"

header: "Review"

multiSelect: false

options:

- label: "Looks correct - proceed"

description: "Write this to the registry"

- label: "Add descriptions"

description: "Let me add descriptions to some sessions"

- label: "Filter some sessions"

description: "Remove sessions that aren't relevant"

- label: "Cancel"

description: "Don't write to registry yet"

```

### Flow E: Choose Output Format

```

AskUserQuestion:

question: "What outputs should be generated?"

header: "Outputs"

multiSelect: true

options:

- label: "registry.jsonl entry (Recommended)"

description: "Master index entry with ALL session UUIDs and GitHub attribution"

- label: "iterations.jsonl entries"

description: "Detailed iteration records in sessions/<id>/"

- label: "Full session chain archive (.jsonl.br)"

description: "Compress sessions with Brotli for archival"

- label: "Markdown finding document"

description: "findings/<name>.md with embedded provenance table"

- label: "Git commit with provenance"

description: "Structured commit message with session references"

- label: "Upload to S3 for team sharing"

description: "Upload artifacts to S3 with retrieval command in commit"

```

### Flow F: Link to Existing ADR

```

AskUserQuestion:

question: "Link this to an existing ADR or design spec?"

header: "ADR Link"

multiSelect: false

options:

- label: "No ADR link"

description: "This is standalone or ADR doesn't exist yet"

- label: "Specify ADR slug"

description: "Link to an existing ADR (e.g., 2025-12-15-feature-name)"

- label: "Create new ADR"

description: "This finding warrants a new ADR"

```

---

## Part 2: Session Archaeology Process

Scan ALL session files, build the `session_contexts` array, and optionally trace UUID chains.

**Full scripts**: [Archaeology Scripts](./references/archaeology-scripts.md)

Summary of steps:

1. **Full Project Scan** - Enumerate all main + subagent sessions with line counts and timestamps

2. **Build session_contexts Array** - Create the array with ALL sessions (session_uuid, type, entries, description)

3. **Trace UUID Chain** (optional) - Follow parent UUID references across sessions for detailed provenance

---

## Part 3: Registry Schema

Two NDJSON files track provenance:

- **`findings/registry.jsonl`** - Master index, one self-contained JSON object per line

- **`findings/sessions/<id>/iterations.jsonl`** - Iteration-level tracking per session

**Full schema, examples, and field reference**: [Registry Schema Reference](./references/registry-schema.md)

### Required Fields (registry.jsonl)

| Field | Format |

| ---------------------------- | ------------------------------------------- |

| `id` | `YYYY-MM-DD-slug` |

| `type` | `research_session` / `finding` / `decision` |

| `created_at` | ISO8601 timestamp |

| `created_by.github_username` | **MANDATORY** GitHub username |

| `session_contexts` | **MANDATORY** Array of ALL session UUIDs |

---

## Part 4: Output Generation

Brotli compression for session archival and structured git commit messages with provenance.

**Full scripts and templates**: [Output Generation](./references/output-generation.md)

Summary:

- **Compression** - Brotli-9 compress each session to `outputs/research_sessions/<id>/*.jsonl.br` (gitignored)

- **Manifest** - Auto-generated `manifest.json` with target_id, count, timestamp

- **Commit message** - Template includes registry_id, attribution, session counts, S3 retrieval commands

---

## Part 5: Confirmation Workflow

### Final Confirmation Before Write

**ALWAYS** show the user what will be written before appending:

```

AskUserQuestion:

question: "Ready to write to registry. Confirm the entry:"

header: "Confirm"

multiSelect: false

options:

- label: "Write to registry"

description: "Append this entry to findings/registry.jsonl"

- label: "Edit first"

description: "Let me modify some fields before writing"

- label: "Cancel"

description: "Don't write anything"

```

Before this question, display:

1. Full JSON entry (pretty-printed)

2. Count of session_contexts entries

3. GitHub username attribution

4. Target file path

### Post-Write Verification

After writing, verify:

```bash

# Validate NDJSON format

tail -1 findings/registry.jsonl | jq . > /dev/null && echo "Valid JSON"

# Show what was written

echo "Entry added:"

tail -1 findings/registry.jsonl | jq '.id, .created_by.github_username, (.session_contexts | length)'

```

---

## Part 6: Workflow Summary

```

1. PREFLIGHT

├── Verify session storage location

├── Find ALL sessions (main + subagent)

└── Check required tools (jq, brotli)

2. ASK: TARGET TYPE

└── AskUserQuestion: What to trace?

3. ASK: GITHUB ATTRIBUTION

└── AskUserQuestion: Who created this?

4. ASK: SESSION SCOPE

└── AskUserQuestion: Which sessions? (Default: ALL)

5. BUILD session_contexts ARRAY

├── Enumerate ALL main sessions

├── Enumerate ALL subagent sessions

└── Collect metadata (entries, timestamps)

6. ASK: PREVIEW session_contexts

└── AskUserQuestion: Review before writing

7. ASK: OUTPUT FORMAT

└── AskUserQuestion: What to generate?

8. ASK: ADR LINK

└── AskUserQuestion: Link to ADR?

9. GENERATE OUTPUTS

├── Build registry.jsonl entry (with iterations_path, iterations_count)

├── Build iterations.jsonl entries (if applicable)

└── Prepare commit message

10. ASK: FINAL CONFIRMATION

└── AskUserQuestion: Ready to write?

11. WRITE & VERIFY

├── Append to registry.jsonl

├── Append to sessions/<id>/iterations.jsonl

└── Validate NDJSON format

12. (OPTIONAL) S3 UPLOAD

└── Upload compressed archives

```

---

## Success Criteria

1. **Complete session enumeration** - ALL main + subagent sessions recorded

2. **GitHub attribution** - `created_by.github_username` always present

3. **Self-contained registry** - Future maintainers don't need archaeology

4. **User confirmation** - Every step has AskUserQuestion confirmation

5. **Valid NDJSON** - All entries pass `jq` validation

6. **Reproducible** - Session UUIDs enable full context retrieval

---

## References

- [S3 Sharing ADR](/docs/adr/2026-01-02-session-chronicle-s3-sharing.md)

- [S3 Retrieval Guide](./references/s3-retrieval-guide.md)

- [Registry Schema Reference](./references/registry-schema.md)

- [Preflight Scripts](./references/preflight-scripts.md)

- [Archaeology Scripts](./references/archaeology-scripts.md)

- [Output Generation](./references/output-generation.md)

- [NDJSON Specification](https://github.com/ndjson/ndjson-spec)

- [jq Manual](https://jqlang.github.io/jq/manual/)

- [Brotli Compression](https://github.com/google/brotli)

---

## Troubleshooting

| Issue | Cause | Solution |

| ------------------------- | --------------------------- | --------------------------------------------------- |

| Session storage not found | Claude Code not initialized | Start a Claude Code session first |

| No sessions in project | Wrong path encoding | Check encoded path matches ~/.claude/projects/ |

| jq parse error | Malformed JSONL | Validate each line with `jq -c .` individually |

| brotli not found | Missing dependency | Install with `brew install brotli` |

| S3 upload fails | Missing AWS credentials | Configure AWS CLI or use 1Password injection |

| UUID chain broken | Session compacted | Check related sessions for continuation |

| GitHub username missing | Attribution not set | Always require github_username in registry entry |

| Registry entry invalid | Missing required fields | Verify id, type, created_at, session_contexts exist |