feat: migrate to skills-based approach
This commit is contained in:
364
.agents/skills/project-history/SKILL.md
Normal file
364
.agents/skills/project-history/SKILL.md
Normal file
@@ -0,0 +1,364 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user