---
name: project-history
description: "Chat-first project memory reconstruction with timeline-first synthesis. Reads AI/chat/session history before git, generates timeline candidates with lanes, and persists resumable workspace memory. Use for: what did I work on recently, what was I doing last time, what changed and why, resume work after break, timeline reconstruction, reconstruct intent from chat, workspace memory scan, next likely tasks, unresolved questions, session continuity across VS Code and VS Code Insiders. WHEN: project history, what did I do yesterday, recent work timeline, continue from last session, chat-first recap, timeline sync, workspace memory."
argument-hint: "[--days N] [--since '2 weeks ago'] [fast|standard|deep]"
---

# Project History Skill

## Mission

Make project continuity reliable by treating timeline as the primary operational artifact.

- Chat/session evidence explains intent.
- Git evidence explains what changed.
- Timeline is the merged contract that drives continuation.

## Progressive Loading Model

Use the smallest level that answers the question.

| Level | Name | Cost | Use when |
|---|---|---:|---|
| L0 | Snapshot | Low | "What was I doing last time?" |
| L1 | Evidence Refresh | Medium | New session likely happened |
| L2 | Timeline Curation | Medium | Need accurate chronology and lanes |
| L3 | Deep Reconstruction | High | Contradictions, missing context, or audit-grade recap |

Reference: [progressive-loading.md](./references/progressive-loading.md)

## Workflow Phases

| Phase | Goal | Entry | Exit |
|---|---|---|---|
| 0 | Snapshot | Always | `state.json` + `timeline.md` read |
| 1 | Evidence Refresh | L1+ | Evidence JSON generated |
| 2 | Timeline Curation | L2+ | `timeline_candidates` validated |
| 3 | Intent + Correlation | L2+ | Chat intent correlated with git/files |
| 4 | Output Synthesis | L2+ | Summary + tasks + questions drafted |
| 5 | Persistence | L1+ | interpreted set + timeline + summary updated |
| 6 | Quality Gate | L1+ | diagnostics/consistency checks pass |

## Phase 0 - Snapshot (L0)

1. Run status:

```powershell
.venv\Scripts\python.exe .agents\skills\project-history\scripts\update_workspace_state.py --status
```

2. Read:
- `_workspace/project-history/state.json`
- `_workspace/project-history/timeline/timeline.md`
- `_workspace/project-history/tasks/active-tasks.json`
- `_workspace/project-history/tasks/unresolved-questions.json`

If this already answers the user question, stop here.

## Phase 1 - Evidence Refresh (L1)

Run collector (workspace cache on by default for normal operation):

```powershell
.venv\Scripts\python.exe .agents\skills\project-history\scripts\collect_evidence.py --days 14 --workspace --diagnostics
```

Optional output file:

```powershell
.venv\Scripts\python.exe .agents\skills\project-history\scripts\collect_evidence.py --days 14 --workspace --diagnostics --output _workspace/project-history/evidence/latest.json
```

Evidence must include:
- `chat_sessions` (primary)
- `chat_sessions_summary`
- `timeline_candidates` (first-class)
- `timeline_preview_md` (human preview)
- `git`, `modified_files`, `todos`, `key_files`

## Phase 2 - Timeline Curation (L2)

Timeline is curated before long-form narrative.

1. Validate timeline candidate quality:
- `timeline_summary.total > 0` where possible
- `timeline_summary.by_source` includes `chat` and/or `git`
- `timeline_summary.by_lane` has sensible distribution

2. Validate lane assignment:
- No lane should dominate due to obvious misclassification
- If lane skew looks wrong, run deep check using [timeline-lanes.md](./references/timeline-lanes.md)

3. If needed, inspect top 3 to 5 session files for correction.

Preferred extraction command (avoid ad-hoc `python -c` and shell quoting):

```bash
python .agents/skills/project-history/scripts/update_workspace_state.py \
  --report-from-evidence _workspace/project-history/evidence/latest.json \
  --report-days 3 \
  --report-candidate-limit 10 \
  --report-commit-limit 5 \
  --write-report-md _workspace/project-history/summaries/live-YYYYMMDD.md
```

Reference: [interpret-evidence.md](./references/interpret-evidence.md)

## Phase 3 - Intent + Correlation (L2)

1. Extract intent from high-relevance chat sessions (`relevance_score >= 7`).
2. Correlate with:
- `git.working_tree`
- `git.commits`
- `modified_files`
3. Mark each claim as:
- `[chat]`
- `[git]`
- `[chat+git]`
- `[conflict]`

## Phase 4 - Output Synthesis (L2)

Produce:
1. Current state summary
2. Reconstructed timeline (date-grouped)
3. What you were likely doing (narrative)
4. Active tasks
5. Open questions
6. Recommended next steps
7. Last 5 worked files with clickable URIs

Use prompt templates when useful:
- [phase-0-fast-context.prompt.md](./prompts/phase-0-fast-context.prompt.md)
- [phase-2-timeline-curation.prompt.md](./prompts/phase-2-timeline-curation.prompt.md)
- [phase-6-persistence.prompt.md](./prompts/phase-6-persistence.prompt.md)

To reopen the latest worked files from current evidence:

```bash
python .agents/skills/project-history/scripts/update_workspace_state.py \
  --recent-files-from-evidence _workspace/project-history/evidence/latest.json \
  --recent-files-count 5 \
  --write-recent-files-md _workspace/project-history/summaries/last-worked-files.md \
  --open-recent-files
```

## Phase 5 - Persistence (L1)

Timeline sync is preferred and mandatory for first-class timeline behavior.

Use one invocation when possible to reduce shell churn:

```bash
python .agents/skills/project-history/scripts/update_workspace_state.py \
  --continuity-from-evidence _workspace/project-history/evidence/latest.json \
  --report-days 3 \
  --report-candidate-limit 10 \
  --report-commit-limit 5 \
  --recent-files-count 5 \
  --write-report-md _workspace/project-history/summaries/live-YYYYMMDD.md \
  --write-recap-md _workspace/project-history/summaries/recap-YYYYMMDD.md \
  --status
```

1. Mark interpreted sessions:

```bash
python .agents/skills/project-history/scripts/update_workspace_state.py \
  --mark-from-evidence _workspace/project-history/evidence/latest.json \
  --mark-min-relevance 7 \
  --mark-summary "Interpreted in project-history run"
```

2. Sync timeline directly from evidence:

```bash
python .agents/skills/project-history/scripts/update_workspace_state.py \
  --sync-timeline-from-evidence _workspace/project-history/evidence/latest.json
```

3. Write summary (optional, requires a pre-generated markdown summary file):

```bash
python .agents/skills/project-history/scripts/update_workspace_state.py \
  --write-summary /path/to/summary.md
```

4. Update focus/state (file-based update preferred to avoid shell escaping):

```bash
python .agents/skills/project-history/scripts/update_workspace_state.py \
  --update-state-file /path/to/state-update.json
```

5. Reopen last worked files (optional but recommended for continuation flow):

```bash
python .agents/skills/project-history/scripts/update_workspace_state.py \
  --recent-files-from-evidence _workspace/project-history/evidence/latest.json \
  --recent-files-count 5 \
  --write-recent-files-md _workspace/project-history/summaries/last-worked-files.md \
  --open-recent-files
```

## Phase 6 - Quality Gate

Run:

```bash
python .agents/skills/project-history/scripts/update_workspace_state.py --status
```

Acceptance checks:
- `sessions interpreted` increased when new chat evidence existed
- `timeline entries` non-decreasing
- `timeline.md` regenerated after sync
- Diagnostics did not show malformed source/lane distribution

Reference: [checklist.md](./references/checklist.md)

## Commands (Quick Reference)

### collect_evidence.py

| Flag | Default | Description |
|---|---:|---|
| `--days N` | 14 | Days to look back |
| `--since TEXT` | - | Override git lookback |
| `--snippets N` | 30 | Max turns per session file |
| `--output FILE` | stdout | Write evidence JSON |
| `--workspace` | off | Enable workspace cache + archive |
| `--full-refresh` | off | Ignore interpreted cache |
| `--diagnostics` | off | Print source/lane diagnostics |

### update_workspace_state.py

| Flag | Description |
|---|---|
| `--status` | Show workspace memory status |
| `--mark-from-evidence FILE` | Bulk mark interpreted chat sessions |
| `--mark-min-relevance N` | Threshold for bulk marking |
| `--mark-summary TEXT` | Summary for interpreted marks |
| `--sync-timeline-from-evidence FILE` | Merge timeline entries and regenerate timeline.md |
| `--timeline-min-relevance N` | Threshold for fallback timeline synthesis |
| `--recent-files-from-evidence FILE` | Build ranked recent-work files and print file URIs |
| `--recent-files-count N` | Number of recent worked files to return (default 5) |
| `--write-recent-files-md FILE` | Write recent-work file list as markdown |
| `--open-recent-files` | Try to open the ranked recent worked files locally |
| `--continuity-from-evidence FILE` | One-shot persist + report + recap flow from evidence |
| `--report-from-evidence FILE` | Generate markdown report with timeline candidates, commits, and worked files |
| `--report-days N` | Time window in days for report filtering (default 3) |
| `--report-candidate-limit N` | Max timeline candidates in report output |
| `--report-commit-limit N` | Max commits in report output |
| `--write-report-md FILE` | Write report markdown to file |
| `--write-recap-md FILE` | Write continuity recap markdown to file |
| `--write-summary FILE` | Write and archive latest summary |
| `--update-state JSON` | Inline state merge |
| `--update-state-file FILE` | File-based state merge |
| `--active-tasks FILE` | Overwrite active tasks |
| `--questions FILE` | Overwrite unresolved questions |

## Companion Assets

- Principles: [principles.md](./references/principles.md)
- Interpretation guide: [interpret-evidence.md](./references/interpret-evidence.md)
- Progressive loading: [progressive-loading.md](./references/progressive-loading.md)
- Timeline lanes: [timeline-lanes.md](./references/timeline-lanes.md)
- Completion checklist: [checklist.md](./references/checklist.md)
- Timeline curator agent: [timeline-curator.agent.md](./agents/timeline-curator.agent.md)

## Non-Negotiables

1. Chat before git for intent reconstruction.
2. Timeline is first-class: always use evidence->timeline sync in Phase 5.
3. Do not dump raw session logs in final user output.
4. Prefer file-based state updates for reliability.
5. If evidence conflicts, prefer chat for intent and git for what happened.
6. Prefer built-in updater report flags over ad-hoc `python -c` JSON extraction.
7. Prefer `--continuity-from-evidence` for standard end-to-end recap runs.