monadical/internalai-agent
13
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
internalai-agent/.agents/skills/project-history/SKILL.md

8.6 KiB
Raw Permalink Blame History

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:

# 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

# 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:

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:

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

# $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

# $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:

# $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:

# 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

### 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

### 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

### 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 View Git Blame Copy Permalink