---
name: project-history
description: Build initial historical timeline for a project. Queries all datasources and creates week-by-week analysis files up to a sync date. Requires project-init to have been run first (datasources.md must exist).
disable-model-invocation: true
argument-hint: [project-name] [date-from] [date-to]
---

# Build Project History

**When to use:** After `/project-init` has been run and the user has reviewed `datasources.md`. This skill gathers historical data and builds the week-by-week timeline.

**Precondition:** `projects/$0/datasources.md` must exist. If it doesn't, run `/project-init $0` first.

## Step 1: Read Datasources

Read `projects/$0/datasources.md` to determine:
- Which Zulip stream IDs and search terms to query
- Which git repository to clone/pull
- Which meeting room names to filter by
- Which entity types to prioritize

## Step 2: Gather Historical Data

Query data for the period `$1` to `$2`.

### A. Query Zulip

For each PRIMARY stream in datasources.md:

```python
# Paginate through all threaded conversations
GET /api/v1/query
  entity_types=threaded_conversation
  connector_ids=zulip
  date_from=$1
  date_to=$2
  search={project-search-term}
  limit=100
  offset=0
```

### B. Clone/Pull Git Repository

```bash
# First time
git clone --depth 200 {url} ./tmp/$0-clone
# Or if already cloned
cd ./tmp/$0-clone && git pull

# Extract commit history for the period
git log --since="$1" --until="$2" --format="%H|%an|%ae|%ad|%s" --date=short
git log --since="$1" --until="$2" --format="%an" | sort | uniq -c | sort -rn
```

### C. Query Meeting Recordings

For each PRIMARY meeting room in datasources.md:

```python
GET /api/v1/query
  entity_types=meeting
  date_from=$1
  date_to=$2
  room_name={room-name}
  limit=100
```

Also do a semantic search for broader coverage:

```python
POST /api/v1/search
  search_text={project-name}
  entity_types=["meeting"]
  date_from=$1
  date_to=$2
  limit=50
```

## Step 3: Analyze by Week

For each week in the period, create a week file. Group the gathered data into calendar weeks (Monday-Sunday).

For each week, analyze:

1. **Key Decisions** — Strategic choices, architecture changes, vendor selections, security responses
2. **Technical Work** — Features developed, bug fixes, infrastructure changes, merges/PRs
3. **Team Activity** — Who was active, new people, departures, role changes
4. **Blockers** — Issues, delays, dependencies

### Week file template

**File:** `projects/$0/timeline/{year-month}/week-{n}.md`

```markdown
# $0 - Week {n}, {Month} {Year}

**Period:** {date-range}
**Status:** [Active/Quiet/Blocked]

## Key Decisions

### Decision Title
- **Decision:** What was decided
- **Date:** {date}
- **Who:** {decision-makers}
- **Impact:** Why it matters
- **Context:** Background

## Technical Work

- [{Date}] {Description} - {Who}

## Team Activity

### Core Contributors
- **Name:** Focus area

### Occasional Contributors
- Name: What they contributed

## GitHub Activity

**Commits:** {count}
**Focus Areas:**
- Area 1

**Key Commits:**
- Hash: Description (Author)

## Zulip Activity

**Active Streams:**
- Stream: Topics discussed

## Current Blockers

1. Blocker description

## Milestones Reached

If any milestones were completed this week, document with business objective:
- **Milestone:** What was achieved
- **Business Objective:** WHY this matters (search for this in discussions, PRs, meetings)
- **Impact:** Quantifiable results if available

## Next Week Focus

- Priority 1

## Notes

- Context and observations
- Always try to capture the WHY behind decisions and milestones
```

### Categorization principles

**Key Decisions:**
- Technology migrations
- Architecture changes
- Vendor switches
- Security incidents
- Strategic pivots

**Technical Work:**
- Feature implementations
- Bug fixes
- Infrastructure changes
- Refactoring

**Skip Unless Meaningful:**
- Routine check-ins
- Minor documentation updates
- Social chat

### Contributor types

**Core Contributors:** Regular commits (multiple per week), active in technical discussions, making architectural decisions, reviewing PRs.

**Occasional Contributors:** Sporadic commits, topic-specific involvement, testing/QA, feedback only.

## Step 4: Create/Update Timeline Index

**File:** `projects/$0/timeline/index.md`

```markdown
# $0 Timeline Index

## {Year}

### {Quarter}
- [Month Week 1](./{year}-{month}/week-1.md)
- [Month Week 2](./{year}-{month}/week-2.md)

## Key Milestones

| Date | Milestone | Business Objective | Status |
|------|-----------|-------------------|--------|
| Mar 2025 | SQLite → PostgreSQL migration | Improve query performance (107ms→27ms) and enable concurrent access for scaling | Complete |
| Jul 2025 | Chakra UI 3 migration | Modernize UI component library and improve accessibility | Complete |

## Summary by Quarter

### Q{X} {Year}
- **Milestone 1:** What happened + Business objective
- **Milestone 2:** What happened + Business objective
```

## Step 5: Create Project Dashboard (project.md)

**File:** `projects/$0/project.md`

Create the **living document** — the entry point showing current status:

```markdown
# $0 Project

**One-liner:** [Brief description]  
**Status:** [Active/On Hold/Deprecated]  
**Last Updated:** [Date]

---

## This Week's Focus

### Primary Objective
[What the team is working on right now - from the most recent week]

### Active Work
- [From recent commits and discussions]

### Blockers
- [Any current blockers]

---

## Last Week's Focus

### Delivered
- ✅ [What was completed]

### Decisions Made
- [Key decisions from last week]

---

## Team

### Core Contributors (Active)
| Name | Focus | Availability |
|------|-------|--------------|
| [From git analysis] | [Area] | Full-time/Part-time |

### Occasional Contributors
- [Name] - [Role]

---

## Milestones

### In Progress 🔄
| Milestone | Target | Business Objective |
|-----------|--------|-------------------|
| [Active milestones from the data] | [Date] | [WHY this matters] |

### Recently Completed ✅
| Milestone | Date | Business Objective |
|-----------|------|-------------------|
| [Recently completed] | [Date] | [WHY this mattered] |

### Lost in Sight / Paused ⏸️
| Milestone | Status | Reason |
|-----------|--------|--------|
| [If any] | Paused | [Why] |

---

## Recent Decisions

### Week [N] (Current)
- **[Decision]** - [Context from data]

---

## Quick Links

- [📊 Timeline](./timeline/index.md) - Week-by-week history
- [📋 Background](./background.md) - Project architecture
- [🔌 Data Sources](./datasources.md) - How to gather information

---

*This is a living document. It reflects the current state and changes frequently.*
```

**Fill in from the analyzed data:**
- Team members from git contributors
- Current focus from the most recent week's activity
- Milestones from major features/deployments found in the data
- Recent decisions from meeting transcripts and Zulip discussions

## Step 6: Update Sync State

Update `projects/$0/sync-state.md`:

```markdown
# Sync State

status: history_complete
created_at: {original date}
last_sync_date: $2
initial_history_from: $1
initial_history_to: $2
```

## Common Patterns

### Security Incident
```markdown
### Security Incident: {CVE-ID}
- **Discovered:** {date}
- **Severity:** CRITICAL/HIGH/MEDIUM
- **Who:** {discoverers}
- **Impact:** {description}
- **Actions:**
  1. Immediate fix
  2. Secrets rotated
  3. Monitoring added
```

### Technology Migration
```markdown
### Migration: {Old} -> {New}
- **Decision:** {date}
- **Who:** {decision-makers}
- **Timeline:** {duration}
- **Rationale:** {why} ← Always include the business objective
- **Status:** Complete/In Progress/Planned
```

**Important:** When documenting any milestone or decision, always search for and include the WHY:
- Performance improvements (quantify if possible: "reduced from X to Y")
- Business capabilities enabled ("allows concurrent access for scaling")
- User experience improvements ("improves accessibility")
- Risk mitigation ("addresses security vulnerability")
- Cost reduction ("eliminates cloud dependency")

Look for this context in: meeting recordings, Zulip planning threads, PR descriptions, release notes.

### Team Change
```markdown
### Team: {Name} {Joined/Left/Role Change}
- **Date:** {date}
- **From:** {old role} (if applicable)
- **To:** {new role}
- **Impact:** {on project}
```

## Key Rules

- **Link to sources**: Always reference commit hashes, PR numbers, Zulip topic names, meeting dates
- **Be explicit about exclusions**: Document what streams/sources you're NOT analyzing and why
- **Write once**: Week files are historical records — don't modify them after creation
- **Paginate all queries**: Result sets can be large, always loop through all pages