Initial commit

2025-11-29 18:26:18 +08:00
commit 7444e5bfb5
12 changed files with 6493 additions and 0 deletions
--- a/skills/project-search/SKILL.md
+++ b/skills/project-search/SKILL.md
@@ -0,0 +1,655 @@
+---
+name: project-search
+description: Search across all project artifacts including meetings, sprints, milestones, documentation, and decisions. Use when user mentions "find", "search", "where is", "locate", "show me", or asks questions about project content. Multi-strategy search using README indexes, pattern matching, and full-text search.
+---
+
+# Project Search Skill
+
+## When to use this Skill
+
+Activate when the user:
+- Asks to find or locate project content
+- Uses keywords: "find", "search", "where is", "locate", "show me"
+- Asks questions about project history or decisions
+- Needs to find meetings, sprints, or documentation
+- Wants to search by person, date, topic, or milestone
+- References specific content they can't locate
+
+## Workflow
+
+### Phase 1: Query Analysis
+
+**Objective**: Understand what the user is searching for and determine search strategy.
+
+**Steps**:
+
+1. **Parse search query** from user message:
+   - Extract search terms
+   - Identify search type (content, person, date, milestone, etc.)
+   - Detect filters (date range, file type, status)
+
+2. **Categorize search intent**:
+   - **Content search**: "Find decisions about database"
+   - **Person search**: "What has @alice worked on"
+   - **Date search**: "Meetings from last week"
+   - **Milestone search**: "What's in beta release milestone"
+   - **Sprint search**: "Show sprint 5 stories"
+   - **Topic search**: "Anything about authentication"
+   - **Status search**: "Show blocked items"
+
+3. **Extract search parameters**:
+   - **Keywords**: Main search terms
+   - **Person**: @mentions or names
+   - **Date range**: "last week", "Q1", "after Jan 1", specific dates
+   - **Content type**: meetings, sprints, docs, decisions, all
+   - **Status**: completed, in-progress, blocked, planned
+   - **Milestone/Sprint**: Specific milestone or sprint number
+
+4. **Determine search scope**:
+   - Project root only
+   - Specific subdirectory (meetings/, sprints/, etc.)
+   - Across entire workspace
+
+**Example Analysis**:
+```
+User: "Find all meetings where we discussed the API design"
+
+Parsed:
+- Intent: Content search
+- Keywords: ["API design"]
+- Content type: meetings
+- Date range: all time
+- Search scope: meetings/
+
+Strategy: README index → Content search in meetings/
+```
+
+### Phase 2: Strategy Selection
+
+**Objective**: Choose optimal search strategy based on query type.
+
+**Search strategies (in order of preference)**:
+
+#### Strategy 1: README.md Index Search (Fastest)
+
+**Use when**:
+- Searching by file name, title, or general topic
+- Need list of files in category
+- Recent content (README indexes are up-to-date)
+
+**Process**:
+1. Read appropriate README.md file:
+   - `meetings/README.md` for meeting search
+   - `sprints/README.md` for sprint search
+   - Project `README.md` for overview
+2. Parse index entries
+3. Filter by search criteria
+4. Return matching entries with descriptions
+
+**Example**:
+```
+Search: "Find sprint 5"
+→ Read sprints/README.md
+→ Find entry: "Sprint 5: Authentication Features"
+→ Return: sprints/sprint-05/sprint-plan.md
+```
+
+#### Strategy 2: YAML/Structured Data Search (Fast)
+
+**Use when**:
+- Searching milestones (milestones.yaml)
+- Searching by metadata (dates, owners, status)
+- Need exact matches on structured fields
+
+**Process**:
+1. Read relevant YAML file (milestones.yaml)
+2. Parse structure
+3. Filter by criteria
+4. Return matching entries
+
+**Example**:
+```
+Search: "Show milestones owned by @alice"
+→ Read milestones.yaml
+→ Filter: owner == "@alice"
+→ Return: List of alice's milestones
+```
+
+#### Strategy 3: Pattern Matching (Fast)
+
+**Use when**:
+- Searching by filename patterns
+- Date-based filename search
+- Type-based search (all *.md in sprints/)
+
+**Process**:
+1. Use `Glob` tool with pattern:
+   - `meetings/**/*2025-11*.md` for November meetings
+   - `sprints/*/sprint-plan.md` for all sprint plans
+   - `docs/**/*.md` for all documentation
+2. Filter results by additional criteria
+3. Return matching files
+
+**Example**:
+```
+Search: "Meetings from November"
+→ Glob: meetings/**/*2025-11*.md
+→ Return: List of November meeting files
+```
+
+#### Strategy 4: Full-Text Content Search (Slower)
+
+**Use when**:
+- Searching for specific terms in content
+- Need to find mentions of topics, names, or concepts
+- Other strategies insufficient
+
+**Process**:
+1. Use `Grep` tool with search terms
+2. Specify scope (meetings/, sprints/, all project)
+3. Extract context around matches
+4. Rank results by relevance
+5. Return matches with snippets
+
+**Example**:
+```
+Search: "Find discussions about OAuth implementation"
+→ Grep: pattern="OAuth" path=meetings/
+→ Find matches in 3 meeting files
+→ Return: Files with context snippets
+```
+
+#### Strategy 5: Cross-Reference Search (Comprehensive)
+
+**Use when**:
+- Need to find all related content
+- Following links and references
+- Building complete picture
+
+**Process**:
+1. Start with initial search (using above strategies)
+2. Read found documents
+3. Extract cross-references (links, mentions, related items)
+4. Follow links recursively (limited depth)
+5. Build relationship map
+6. Return full result set with connections
+
+**Example**:
+```
+Search: "Everything about beta release milestone"
+→ Find milestone in milestones.yaml
+→ Follow related_sprints links
+→ Find meetings mentioning beta release
+→ Find docs created for beta
+→ Return: Complete set with relationships
+```
+
+### Phase 3: Execute Search
+
+**Objective**: Run selected search strategy and gather results.
+
+**Steps**:
+
+1. **Execute primary search strategy**
+
+2. **Collect results**:
+   - File paths
+   - Titles/descriptions
+   - Relevant metadata (dates, owners, status)
+   - Content snippets (for full-text search)
+
+3. **Apply filters**:
+   - Date range filter
+   - Person filter (@mentions)
+   - Status filter
+   - Content type filter
+
+4. **Check governance** (if applicable):
+   - Read RULE.md for access restrictions
+   - Filter out restricted content
+
+5. **Rank results** by:
+   - **Relevance**: Match quality to query
+   - **Recency**: Newer content ranked higher
+   - **Location**: Closer to project root ranked higher
+   - **Completeness**: Fully completed items vs drafts
+
+6. **If no results from primary strategy**:
+   - Fall back to next strategy
+   - Broaden search criteria
+   - Suggest related searches
+
+### Phase 4: Format and Present Results
+
+**Objective**: Present search results in clear, actionable format.
+
+**Steps**:
+
+1. **Group results** by category:
+   - Meetings
+   - Sprints/Iterations
+   - Milestones
+   - Documentation
+   - Decisions
+
+2. **Format result entries**:
+   ```
+   📄 [Category] Title
+      Path: path/to/file.md
+      Date: YYYY-MM-DD
+      [Relevant metadata: Owner, Status, etc.]
+      [If content search: Context snippet with highlights]
+   ```
+
+3. **Include result count and search details**:
+   ```
+   🔍 Search Results for "{query}"
+
+   Found {count} results in {categories}
+   Search scope: {scope}
+   Filters applied: {filters if any}
+   ```
+
+4. **Present results**:
+
+   **Format**:
+   ```
+   🔍 Search Results: "{query}"
+
+   Found {total} results across {categories}
+
+   📋 Meetings ({count})
+   - [2025-11-13: Sprint 5 Planning](meetings/sprint-planning/2025-11-13_sprint-5-planning.md)
+     "Discussed API design for authentication endpoints..."
+
+   - [2025-11-06: Architecture Review](meetings/general/2025-11-06_api-architecture.md)
+     "@alice presented OAuth 2.0 implementation options..."
+
+   🏃 Sprints ({count})
+   - [Sprint 5: Authentication Features](sprints/sprint-05/sprint-plan.md)
+     Status: Active | Stories: 8 | Owner: @bob
+
+   🎯 Milestones ({count})
+   - [Beta Release](milestones.yaml#beta-release)
+     Target: 2025-03-31 | Status: In Progress | Progress: 75%
+
+   📚 Documentation ({count})
+   - [API Design Document](docs/api-design.md)
+     Owner: @alice | Updated: 2025-11-10
+
+   🔗 Cross-References ({count})
+   [If cross-reference search performed]
+   - Sprint 5 → Beta Release Milestone
+   - API Design Doc → Sprint 5 Stories
+   - Sprint Planning → Architecture Review Meeting
+   ```
+
+5. **Offer refinement options**:
+   ```
+   💡 Refine your search:
+   - "Show only completed"
+   - "Find from last month"
+   - "Search only in sprints"
+   - "Show details for [specific result]"
+   ```
+
+6. **If too many results**:
+   ```
+   ℹ️ Showing top {limit} results. {remaining} more found.
+
+   Narrow your search:
+   - Add date range: "from last week"
+   - Specify type: "only meetings"
+   - Add filters: "owned by @name"
+   ```
+
+7. **If no results**:
+   ```
+   🔍 No results found for "{query}"
+
+   Suggestions:
+   - Check spelling
+   - Try broader terms
+   - Search related terms: "{suggestions}"
+   - Search in different location
+
+   Recent content:
+   [Show recently added/updated files as alternatives]
+   ```
+
+### Phase 5: Detailed View (Optional)
+
+**Objective**: If user wants details on specific result, provide full context.
+
+**Steps**:
+
+1. **If user selects specific result**:
+   ```
+   User: "Show me the sprint 5 details"
+   ```
+
+2. **Read full document**:
+   ```
+   Read sprints/sprint-05/sprint-plan.md
+   ```
+
+3. **Present complete information**:
+   ```
+   📄 Sprint 5: Authentication Features
+
+   **Status**: Active (Day 8 of 14)
+   **Goal**: Complete user authentication and profile management
+   **Dates**: 2025-11-01 to 2025-11-14
+
+   **Progress**:
+   - Completed: 3/8 stories (18/45 points) - 40%
+   - In Progress: 2 stories
+   - Blocked: 1 story (OAuth config)
+
+   **Team**:
+   - @alice: 2 stories
+   - @bob: 3 stories
+   - @carol: 2 stories
+   - @david: 1 story
+
+   **Related**:
+   - Milestone: Beta Release (contributes to)
+   - Meetings: [Sprint 5 Planning](link), [Daily Standups](link)
+   - Docs: [Auth Design](link)
+
+   📄 Full document: sprints/sprint-05/sprint-plan.md
+
+   💡 Actions:
+   - "Update sprint 5 progress"
+   - "Show sprint 5 meetings"
+   - "Mark story complete in sprint 5"
+   ```
+
+## Special Cases
+
+### Case 1: Person-specific search
+
+```
+User: "What has @alice been working on?"
+
+Process:
+1. Search all content for @alice mentions
+2. Filter by recency (last sprint/month)
+3. Categorize:
+   - Assigned stories/tasks
+   - Meeting attendances
+   - Owned milestones
+   - Created documents
+
+Result:
+📊 @alice's Recent Activity
+
+**Current Work** (Sprint 5):
+- Story: OAuth Integration (8sp) - In Progress
+- Story: Profile Edit Page (3sp) - Completed ✅
+
+**Meetings** (Last 2 weeks):
+- Sprint 5 Planning (2025-11-01)
+- Architecture Review (2025-11-06)
+- Daily Standups (10 attendances)
+
+**Milestones**:
+- Owner: Security Audit (Target: 2025-03-20)
+
+**Documents**:
+- Created: API Design Doc (2025-11-10)
+- Updated: Auth Spec (2025-11-08)
+```
+
+### Case 2: Timeline/Date-based search
+
+```
+User: "What happened in the project last week?"
+
+Process:
+1. Calculate date range (last week)
+2. Search all content within range
+3. Sort chronologically
+4. Group by day
+
+Result:
+📅 Project Activity: Nov 6 - Nov 13, 2025
+
+**Monday, Nov 6**
+- Meeting: Sprint 4 Retrospective
+- Sprint 4 completed (38/40 points)
+- Milestone updated: Beta Release (60% → 75%)
+
+**Tuesday, Nov 7**
+- Sprint 5 started
+- Stories assigned to team
+
+**Wednesday, Nov 8**
+- Daily standup recorded
+- Decision: Use PostgreSQL for auth
+
+**[Continue for each day]**
+
+📊 Week Summary:
+- Meetings: 8
+- Stories completed: 5
+- Documents updated: 3
+- Milestones progressed: 1
+```
+
+### Case 3: Topic/Theme search
+
+```
+User: "Find everything about database decisions"
+
+Process:
+1. Full-text search for "database"
+2. Focus on decisions/ directory
+3. Also search meetings and docs
+4. Cross-reference related content
+
+Result:
+🔍 Search: "database"
+
+📋 Decisions (3):
+- [001: Database Selection](decisions/001-database-choice.md)
+  PostgreSQL chosen for auth system (2025-10-15)
+
+- [005: Caching Strategy](decisions/005-caching.md)
+  Redis for session caching (2025-10-20)
+
+- [012: Migration Approach](decisions/012-database-migration.md)
+  Flyway for schema versioning (2025-11-01)
+
+📋 Meetings discussing database (4):
+- Architecture Review (2025-10-15)
+- Sprint 3 Planning (2025-10-16)
+- Tech Spike Results (2025-10-19)
+- Database Design Session (2025-10-22)
+
+📚 Related Documentation (2):
+- Database Schema (docs/database-schema.md)
+- Migration Guide (docs/migration-guide.md)
+
+🏃 Related Sprints:
+- Sprint 3: Database setup and migration
+
+🔗 Cross-references:
+All database decisions link to Sprint 3 and Beta Release milestone
+```
+
+### Case 4: Status-based search
+
+```
+User: "Show me all blocked items"
+
+Process:
+1. Search sprints for status: blocked
+2. Search milestones for status: delayed
+3. Search meetings for blocker discussions
+
+Result:
+⚠️ Blocked Items
+
+🏃 Sprints:
+- Sprint 5, Story: OAuth Integration
+  Blocked: Waiting for third-party API credentials
+  Owner: @alice
+  Blocked since: 2025-11-10
+
+📋 Meetings mentioning blockers:
+- Daily Standup (2025-11-10)
+- Daily Standup (2025-11-11)
+- Daily Standup (2025-11-13)
+
+💡 Action needed:
+- @alice: Follow up on API credentials
+- Consider workaround or mock implementation
+```
+
+## Error Handling
+
+### Error: No RULE.md found
+
+```
+⚠️ No RULE.md found.
+
+Search will proceed with default project structure.
+
+Note: For best results, initialize project governance:
+"Initialize project"
+```
+
+Proceed with search using standard directories.
+
+### Error: No results found
+
+```
+🔍 No results found for "{query}"
+
+Checked:
+- ✓ Meetings
+- ✓ Sprints
+- ✓ Milestones
+- ✓ Documentation
+- ✓ Decisions
+
+Suggestions:
+- Check spelling: "{query}"
+- Try broader terms
+- Try related searches:
+  * "{suggestion 1}"
+  * "{suggestion 2}"
+
+📋 Recent project activity:
+[Show last 5 updates as alternatives]
+```
+
+### Error: Search too broad
+
+```
+ℹ️ Your search "{query}" returned {count} results.
+
+This may be too many to review effectively.
+
+Suggestions to narrow:
+1. Add date range: "from last month"
+2. Specify type: "only in meetings"
+3. Add person filter: "by @name"
+4. Add status: "completed only"
+
+Or continue with:
+"Show top 10 results"
+```
+
+### Error: Invalid date range
+
+```
+⚠️ Could not parse date: "{date_input}"
+
+Supported formats:
+- Specific: "2025-11-13" or "November 13, 2025"
+- Relative: "last week", "last month", "yesterday"
+- Range: "from Nov 1 to Nov 15"
+- Quarter: "Q1", "Q2 2025"
+
+Please rephrase your date filter.
+```
+
+## Integration with Other Skills
+
+### With AkashicRecords search-content
+
+Both Skills can search same project:
+- AkashicRecords: Knowledge base, articles, general content
+- ProjectMaster: Project-specific content (meetings, sprints, milestones)
+
+If both exist, search both and merge results.
+
+### With track-meeting Skill
+
+Found meetings can be:
+- Viewed in detail
+- Updated
+- Linked to other content
+
+### With manage-sprint Skill
+
+Found sprints can be:
+- Updated with progress
+- Viewed in detail
+- Cross-referenced with milestones
+
+### With track-milestone Skill
+
+Found milestones can be:
+- Updated with status
+- Viewed with full dependencies
+- Linked to contributing sprints
+
+## Best Practices
+
+### 1. Start with README indexes
+
+Fastest search method. Always try first.
+
+### 2. Use specific search terms
+
+Specific terms yield better results than generic ones.
+
+### 3. Add filters to narrow results
+
+Date ranges, content types, and person filters improve relevance.
+
+### 4. Follow cross-references
+
+Related content often provides fuller picture.
+
+### 5. Search by person for team insights
+
+Find what specific team members are working on or have created.
+
+### 6. Use date-based search for retrospectives
+
+"What did we do last sprint?" captures recent history.
+
+### 7. Search by milestone for big picture
+
+See all content contributing to major goals.
+
+### 8. Combine search strategies
+
+If one strategy fails, automatically try next.
+
+## Notes
+
+- Multi-strategy search ensures comprehensive results.
+- README index search is fast and accurate for well-maintained projects.
+- Full-text search is powerful but slower - use as fallback.
+- Cross-reference search builds complete context around topics.
+- Search results link to Skills that can act on found content.
+- Person-based and date-based searches provide valuable team insights.
+
+---
+
+Effective search transforms project content into accessible knowledge. This Skill makes finding information fast and intuitive.