--- 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//iterations.jsonl` | YES | Iteration records (small, append-only) | | `outputs/research_sessions//` | NO | Research artifacts (large, gitignored) | | `tmp/` | NO | Temporary archives before S3 upload | | S3 `eonlabs-findings/sessions//` | 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//" - label: "Full session chain archive (.jsonl.br)" description: "Compress sessions with Brotli for archival" - label: "Markdown finding document" description: "findings/.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//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//*.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//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 |