zhongwei/gh-tommy-ca-notion-skills-plugins-notion-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:02:23 +08:00
commit 5f44d04a64
18 changed files with 1976 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,13 @@
{
"name": "notion-skills",
"description": "Comprehensive collection of Claude skills for Notion integration: capture knowledge from conversations, prepare for meetings, conduct research, and convert specifications into implementation plans",
"version": "1.0.0",
"author": {
"name": "Anthropic & Notion",
"email": "contact@notion.so",
"url": "https://notion.so"
},
"skills": [
"./skills"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# notion-skills
Comprehensive collection of Claude skills for Notion integration: capture knowledge from conversations, prepare for meetings, conduct research, and convert specifications into implementation plans

101
plugin.lock.json Normal file
View File

@@ -0,0 +1,101 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:tommy-ca/notion-skills:plugins/notion-skills",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "c2bf0d43f6a1fbceba0a8cf1710b7f5faa752ecd",
"treeHash": "dc0980c23040842a929f4267eb5a5de6ced9f6acfd23b4c307b2d6c3fa61490b",
"generatedAt": "2025-11-28T10:28:42.997121Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "notion-skills",
"description": "Comprehensive collection of Claude skills for Notion integration: capture knowledge from conversations, prepare for meetings, conduct research, and convert specifications into implementation plans",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "1cdc66692fb0a107ec801af20f1f72117fd1c0853600bac2a358fa16092f27c3"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "f8c7245c75a9b15038e16382668a5c2e2da562a567b6f8bc868784d2a90cb861"
},
{
"path": "skills/research-documentation/SKILL.md",
"sha256": "52ef342bd49eca1c54a2b6ffc16e7b2423cafffc1d1f9bec8b42fcd2102c9e49"
},
{
"path": "skills/research-documentation/evaluations/README.md",
"sha256": "9244181d792fbf575bcdde6093c04edcd2ead5b945a947b3d77b697b15c9f329"
},
{
"path": "skills/research-documentation/reference/format-guide.md",
"sha256": "99c69fd8cd6215cc077d166720bb0cbc151e6a6604f0334f905db931b80ea5a4"
},
{
"path": "skills/meeting-intelligence/SKILL.md",
"sha256": "b525db7ff62f482d04c60244eb65afd80d61b3e56cd59842bebcead71ddbb3b3"
},
{
"path": "skills/meeting-intelligence/evaluations/README.md",
"sha256": "5ff6bc89abd5978e53b0d06398a09c22e2ad06fe4145bbc3c3ce76ebe05975b5"
},
{
"path": "skills/meeting-intelligence/reference/agenda-structure-guide.md",
"sha256": "cdb5518eb02dd00cba9a6de9689a25ab35096350ada1f21a74c76d647ce81bfe"
},
{
"path": "skills/knowledge-capture/SKILL.md",
"sha256": "a39a68b5158fc1c5315e78aa0fc4eb317f19232169e46b5c6c4fb0a3a7e74247"
},
{
"path": "skills/knowledge-capture/evaluations/README.md",
"sha256": "e372917ad2400ee052b6a62448717ba71e87e943d9511bdf139088e4288fed25"
},
{
"path": "skills/knowledge-capture/evaluations/scenario-1-meeting-notes.json",
"sha256": "17ae28dd5385f8c90c27f80e98b6385060a17d750a0f484edf7443d379db75cb"
},
{
"path": "skills/knowledge-capture/examples/example-meeting-summary.md",
"sha256": "3fce55dafa1dd0e1760830d1a5bfdb15ad623c97d4211b40a0d713e97dd525b1"
},
{
"path": "skills/knowledge-capture/reference/best-practices.md",
"sha256": "a3c409aa473fcfcc4de5e87f4431d09e609cdf1c0cf02fd26f9605b436f16768"
},
{
"path": "skills/knowledge-capture/reference/documentation-types.md",
"sha256": "03884877c39869a323ebb7882256c9b914357db5c7eace5f767e15929d9eaa9d"
},
{
"path": "skills/spec-to-implementation/SKILL.md",
"sha256": "6d4ed506ade58c570e0292640d9cf30af6dee1181c25d4a0635e5263fd55d77f"
},
{
"path": "skills/spec-to-implementation/evaluations/README.md",
"sha256": "7d56ee5c19d1f698b7790d348f7c13887892206e362dd4bd88e853b1689b7d6b"
},
{
"path": "skills/spec-to-implementation/reference/task-breakdown-guide.md",
"sha256": "f5d0647b2808d4b1b7f80d09b7c10419404571af0689902ea6ab94d40ce7016f"
}
],
"dirSha256": "dc0980c23040842a929f4267eb5a5de6ced9f6acfd23b4c307b2d6c3fa61490b"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

90
skills/knowledge-capture/SKILL.md Normal file
View File

@@ -0,0 +1,90 @@
---
name: knowledge-capture
description: Transform conversations and discussions into structured Notion documentation
---
## Overview
The Knowledge Capture skill transforms conversations, discussions, and unstructured information into organized, structured documentation in Notion. It helps you preserve institutional knowledge by capturing important conversations and converting them into actionable, well-formatted documentation.
## When to Use
Use this skill when you need to:
- Convert transcripts or conversation notes into structured documentation
- Create meeting summaries with action items
- Build knowledge base articles from discussions
- Archive important conversations for future reference
- Extract key insights and decisions from discussions
## Features
- **Smart Content Extraction**: Automatically identifies key points, decisions, and action items from conversations
- **Structured Organization**: Creates well-organized Notion documents with proper hierarchy
- **Metadata Capture**: Preserves participants, dates, and context information
- **Action Item Tracking**: Extracts and formats action items with ownership and deadlines
- **Cross-linking**: Automatically creates links to related documentation and team members
## Requirements
- **Notion API Access**: Integration token with appropriate permissions
- **Target Workspace**: Notion workspace where documentation will be stored
- **Template (Optional)**: Pre-defined Notion template for consistent structure
## Implementation Details
This skill uses the Notion API to:
1. Parse input content (text, transcripts, or discussion notes)
2. Extract key information using structural analysis
3. Format content according to Notion document standards
4. Create or update Notion pages with captured knowledge
5. Maintain cross-references and relationships
### Typical Workflow
```
Input: Conversation/Discussion
↓
Parse & Extract
↓
Identify: Key Points, Decisions, Action Items
↓
Format for Notion
↓
Create/Update Notion Document
↓
Output: Structured Documentation
```
## Example Use Cases
1. **Team Meeting Notes**
- Input: Meeting transcript
- Output: Organized meeting summary with decisions and next steps
2. **Customer Call Documentation**
- Input: Call notes and transcript
- Output: Customer interaction record with key requirements
3. **Architecture Discussion**
- Input: Design discussion notes
- Output: Architectural decision record with alternatives and rationale
4. **Interview Notes**
- Input: Interview transcript
- Output: Structured candidate or user research documentation
## Configuration
Set up these environment variables or Notion settings:
```env
NOTION_API_TOKEN=your_token_here
NOTION_DATABASE_ID=your_database_id
```
## See Also
- [Research Documentation](/skills/research-documentation) - For research-focused documentation
- [Meeting Intelligence](/skills/meeting-intelligence) - For meeting preparation and follow-up
- [Notion API Documentation](https://developers.notion.com)

142
skills/knowledge-capture/evaluations/README.md Normal file
View File

@@ -0,0 +1,142 @@
# Knowledge Capture - Evaluation Scenarios
This directory contains test scenarios for validating the Knowledge Capture skill across different Claude models.
## Overview
These evaluations ensure that Knowledge Capture works consistently and effectively with:
- Claude 3 Haiku
- Claude 3 Sonnet
- Claude 3 Opus
Each scenario includes:
- **Input**: The conversation or content to capture
- **Expected Behavior**: What the skill should do
- **Success Criteria**: How to verify success
## Running Evaluations
### Manual Testing
1. Copy the conversation/input from a scenario
2. Activate Knowledge Capture skill in Claude Code
3. Request to capture it as specified
4. Evaluate against the success criteria
### Test Coverage
- Basic conversation capture
- Different documentation types
- Complex multi-topic discussions
- Action item extraction
- Decision documentation
- Error handling
## Scenarios
### scenario-1-meeting-notes.json
**Type**: Meeting Summary Capture
**Complexity**: Medium
**Input**: Unstructured meeting notes from a team discussion
**Expected Output**: Structured meeting summary with decisions and action items
**Success Criteria**: All action items identified, decisions documented, participants listed
### scenario-2-architecture-discussion.json
**Type**: Decision Record Capture
**Complexity**: Medium-High
**Input**: Complex technical architecture discussion
**Expected Output**: Decision record with options considered and rationale
**Success Criteria**: All alternatives documented, clear decision stated, consequences identified
### scenario-3-quick-context.json
**Type**: Quick Capture
**Complexity**: Low
**Input**: Brief status update
**Expected Output**: Quick reference document
**Success Criteria**: Key points captured, properly formatted
### scenario-4-action-items-focus.json
**Type**: Action Item Extraction
**Complexity**: Medium
**Input**: Meeting with many scattered action items
**Expected Output**: Clear list of who, what, when
**Success Criteria**: All action items found, owners assigned, deadlines noted
### scenario-5-learning-from-incident.json
**Type**: Learning Document
**Complexity**: High
**Input**: Post-incident discussion about what went wrong
**Expected Output**: Learning document with best practices
**Success Criteria**: Root causes identified, lessons extracted, preventive measures noted
## Evaluation Criteria
### Comprehensiveness
- Did the skill capture all key information?
- Were important details missed?
- Is the output complete?
### Structure
- Is the output well-organized?
- Are headings and sections appropriate?
- Does it follow the documentation type's structure?
### Actionability
- Are action items clear and assignable?
- Are next steps defined?
- Can someone understand what to do next?
### Linking
- Are cross-references included?
- Could this be discovered from related docs?
- Are important connections made?
### Accuracy
- Is the captured information accurate?
- Were details misinterpreted?
- Does it faithfully represent the source?
## Model-Specific Notes
### Haiku
- May need slightly more structured input
- Evaluates on accuracy and completeness
- Good for quick captures
### Sonnet
- Handles complex discussions well
- Good at inferring structure
- Balanced performance across all scenario types
### Opus
- Excels at inferring structure from unstructured input
- Best for complex, multi-topic discussions
- Highest accuracy on nuanced extraction
## Failure Modes to Watch For
1. **Orphaning**: Documentation created without linking to hub pages
2. **Structure Loss**: Loss of hierarchical organization
3. **Missing Details**: Key decisions or action items not captured
4. **Wrong Type**: Documentation created as wrong type (e.g., FAQ instead of Decision Record)
5. **Broken Context**: Missing important contextual information
6. **Inaccuracy**: Misinterpretation of what was discussed
## Updating Scenarios
When updating scenarios:
1. Ensure they reflect real-world use cases
2. Include edge cases and challenging inputs
3. Keep success criteria clear and measurable
4. Test with all three model sizes
5. Document any model-specific behavior
## Expected Performance
**Target Success Rate**: 90%+ on Sonnet and Opus, 85%+ on Haiku
When a scenario fails:
1. Review the specific failure mode
2. Check if it's a consistent issue or model-specific
3. Update the skill prompt if needed
4. Document the failure and resolution

99
skills/knowledge-capture/evaluations/scenario-1-meeting-notes.json Normal file
View File

@@ -0,0 +1,99 @@
{
"id": "scenario-1-meeting-notes",
"name": "Meeting Notes Capture",
"description": "Convert unstructured meeting notes into a structured meeting summary",
"complexity": "medium",
"input_type": "meeting_notes",
"output_type": "meeting_summary",
"input": {
"context": "Team planning meeting about Q4 roadmap",
"content": "Had a meeting today with product, engineering, and design about Q4 priorities. We talked about the fact that customers have been asking for dark mode for a while - it's our most requested feature. Sarah (PM) said we should prioritize it, and Mike (design) showed mockups that look great. The engineering team (me, Alex, and Jordan) think we can get it done in 2 sprints if we focus. We also talked about the mobile app - James mentioned that iOS performance is slow when rendering large lists. We didn't decide on a timeline for that yet. Alex volunteered to look into virtualization. For dark mode, we decided to ship it with a toggle in settings that persists to the database. Next steps: Sarah will write the spec this week, Mike will finalize designs by end of week, and our team will start on implementation next sprint. We also have some tech debt from the old auth system that Mike thinks is slowing us down, but we deferred that to next quarter. Finally, we need a QA plan for dark mode - Jessica said she'd put together a testing plan."
},
"expected_output": {
"document_type": "meeting_summary",
"structure": {
"title": "Q4 Roadmap Planning - Team Meeting",
"sections": [
"Meeting Details",
"Key Decisions",
"Action Items",
"Topics Discussed",
"Deferred Items"
]
},
"key_decisions": [
{
"decision": "Prioritize dark mode implementation",
"rationale": "Most frequently requested customer feature"
},
{
"decision": "Dark mode will use toggle in settings with database persistence",
"rationale": "User preference persistence requirement"
}
],
"action_items": [
{
"owner": "Sarah",
"task": "Write dark mode specification",
"deadline": "This week"
},
{
"owner": "Mike",
"task": "Finalize dark mode design mockups",
"deadline": "End of week"
},
{
"owner": "Engineering team",
"task": "Begin dark mode implementation",
"deadline": "Next sprint"
},
{
"owner": "Alex",
"task": "Investigate list virtualization for iOS performance",
"deadline": "TBD"
},
{
"owner": "Jessica",
"task": "Create QA test plan for dark mode",
"deadline": "TBD"
}
],
"attendees": [
"Sarah (Product)",
"Mike (Design)",
"Engineering: self, Alex, Jordan",
"James (mentioned iOS issues)",
"Jessica (QA)"
]
},
"success_criteria": {
"must_capture": [
"Meeting purpose and date",
"All participants/roles",
"Both major decisions with rationale",
"All 5 action items with owners and deadlines",
"Topics discussed (dark mode, mobile performance, tech debt)",
"Implementation timeline (2 sprints for dark mode)"
],
"should_capture": [
"Design mockups mentioned",
"Tech debt deferred to Q1",
"Connection to customer requests"
],
"must_not_do": [
"Invent action items not mentioned",
"Misassign ownership",
"Lose deadline information",
"Create orphaned document without linking context"
]
},
"evaluation_notes": {
"difficulty": "Medium - requires extracting structure from unstructured narrative",
"key_challenge": "Identifying implicit decisions and action items from conversation flow",
"model_variations": {
"haiku": "May miss some implicit items, but should catch main points",
"sonnet": "Should capture all explicit items and most implicit ones",
"opus": "Should capture full context with implicit relationships"
}
}
}

115
skills/knowledge-capture/examples/example-meeting-summary.md Normal file
View File

@@ -0,0 +1,115 @@
# Example: Meeting Summary Capture
## Before (Raw Input)
```
Had a good meeting today with the product and design teams about authentication.
We talked about moving to passwordless auth using passkeys. Sarah brought up
that we need to support legacy systems, so we can't go all-in yet. Mike showed
designs for the new flow - looks great. We decided to do a phased rollout:
Phase 1 is passkeys in web, Phase 2 is mobile, Phase 3 is legacy support.
Sarah will write the spec, Mike will handle design across all phases, and I'll
coordinate engineering. We also talked about the performance issues with the
current auth - not a blocker but something we should keep an eye on. The new
architecture should fix that anyway. Need to talk to infra about deployment,
and we'll need a migration plan for existing users.
```
## After (Captured in Notion)
### Meeting Summary: Passwordless Authentication Strategy
**Date:** November 9, 2025
**Attendees:** Sarah (Product), Mike (Design), Engineering Lead
**Duration:** 1 hour
**Status:** Decisions Made
---
## Key Decisions
### Decision 1: Implement Passwordless Authentication via Passkeys
- **Decision:** Migrate to passkey-based authentication
- **Rationale:** Improved security and user experience
- **Phase Approach:** Phased rollout required due to legacy system constraints
### Decision 2: Phased Rollout Strategy
- **Phase 1:** Passkeys in web applications
- **Phase 2:** Mobile app support
- **Phase 3:** Legacy system support and migration
- **Rationale:** Allows gradual adoption while maintaining backward compatibility
---
## Action Items
| Owner | Task | Deadline | Status |
|-------|------|----------|--------|
| Sarah (Product) | Write passwordless auth specification with phase requirements | This week | Not Started |
| Mike (Design) | Create design mockups for all authentication flows across phases | End of week | In Progress |
| Engineering Lead | Coordinate engineering effort and infrastructure planning | Next sprint | Not Started |
| Infrastructure | Plan deployment strategy and production rollout approach | TBD | Not Started |
---
## Discussion Topics
### Passwordless Authentication
- Passkeys provide strong security posture
- User experience benefits over traditional passwords
- Industry standard approach (WebAuthn/FIDO2)
### Legacy System Constraints
- Cannot immediately deprecate password authentication
- Existing systems require continued support
- Migration path needed for users on legacy platforms
### Performance Considerations
- Current auth system has performance overhead
- New architecture should resolve existing performance issues
- Not a blocker for implementation but important improvement
### Migration Planning
- Need clear plan for existing user migration
- Gradual rollout reduces risk
- Each phase builds on previous phase
---
## Next Steps
1. **This Week:** Sarah delivers detailed specification
2. **End of Week:** Design mockups finalized for review
3. **Next Sprint:** Engineering begins Phase 1 (web) implementation
4. **Parallel:** Infrastructure team plans deployment and migration strategy
5. **TBD:** User communication plan for authentication transition
---
## Related Documents
- [Authentication Architecture Decision Record](notion://decision-record-url)
- [Security Requirements Specification](notion://spec-url)
- [Q4 Product Roadmap](notion://roadmap-url)
- [Infrastructure Planning](notion://infra-url)
## Tags
`authentication` `security` `product-initiative` `phased-rollout` `decision-record`
## Follow-up Items
- [ ] Schedule follow-up meeting after specs are written
- [ ] Plan QA testing strategy for each phase
- [ ] Create user communication plan
- [ ] Schedule infrastructure review of deployment plan
---
## Notes
- **Performance improvement** is a nice-to-have benefit of new architecture
- **Backward compatibility** is critical for adoption success
- **Phasing** reduces implementation risk and allows for feedback cycles
**Owner:** Sarah (Product) | **Last Updated:** November 9, 2025 | **Next Review:** November 23, 2025

161
skills/knowledge-capture/reference/best-practices.md Normal file
View File

@@ -0,0 +1,161 @@
# Knowledge Capture - Best Practices
Guidelines for capturing knowledge effectively in Notion.
## Timing
**Capture Promptly**
- Document while context is fresh
- Aim to capture within 24 hours of the conversation
- Create placeholder if you'll document later
**Regular Maintenance**
- Review quarterly for accuracy
- Update links if pages move
- Archive outdated documentation
- Mark superseded content clearly
## Structure & Organization
**Clear Hierarchy**
- Use proper heading levels (H1, H2, H3, etc.)
- One main idea per section
- Logical flow from overview to details
- Include table of contents for long documents
**Consistent Templates**
- Use the same structure within document types
- Keep headers and sections predictable
- Use consistent formatting and styles
## Content Quality
**Be Specific**
- Use concrete examples over vague descriptions
- Include actual code, commands, or workflows
- Name specific tools and versions
- Be clear about what's required vs. optional
**Make It Actionable**
- Include clear next steps
- Provide decision criteria if applicable
- List prerequisites upfront
- Specify who needs to do what
**Prevent Orphaning**
- Link to hub pages or indexes
- Add to relevant category pages
- Use tags for discovery
- Include "Related Documents" section
## Linking & Discoverability
**Strategic Linking**
```
Example: How-To Guide on "Setting Up CI/CD"
Links to add:
- Source document (e.g., architecture decision)
- Related documents (deployment guide, monitoring)
- Hub page (DevOps/Infrastructure index)
- Team/person pages (who uses this)
```
**Tagging Strategy**
- Use consistent tag names across org
- Don't over-tag (3-5 tags per document)
- Use hierarchical tags: `process/deployment`, `tool/github`
- Example tags: `how-to`, `urgent`, `team-core`, `deprecated`
**Searchable Content**
- Use descriptive titles (not "Meeting Notes", use "Q4 Planning - Nov 9")
- Include keywords in description
- Put important terms in headings
- Use consistent terminology
## Collaborative Documentation
**Ownership & Updates**
- Designate an owner for each document
- Include last-updated date
- Make update process clear (who can edit)
- Document version/change history if needed
**Review Cycle**
- Schedule reviews for time-sensitive docs (quarterly for most)
- Mark review dates in document
- Create task reminders for reviews
- Document what changed and why
**Avoiding Duplication**
- Search before creating new docs
- Link to existing docs instead of copying
- Mark outdated docs clearly
- Consolidate when possible
## Different Formats
**Short Documents (< 5 screens)**
- Single Notion page
- No special structure needed
- Still add tags and links
**Medium Documents (5-20 screens)**
- Use databases for modular content
- Create table of contents
- Add navigation between sections
**Long Documents (> 20 screens)**
- Consider breaking into multiple pages
- Create parent pages with sub-pages
- Add clear navigation
- Link to each section from TOC
## Maintenance Patterns
**Quarterly Review Checklist**
- [ ] Is this still accurate?
- [ ] Are links still valid?
- [ ] Should we archive or consolidate?
- [ ] Are examples still relevant?
- [ ] Do we need to update tools/versions?
**Update Notification**
- When updating significant docs: notify stakeholders
- Add summary of what changed
- Update linked documents if needed
- Note the update in a changelog if important
## Common Pitfalls to Avoid
1. **Orphaned Documentation**: Always link to hub pages
2. **Outdated Examples**: Date-stamp time-sensitive information
3. **Vague Instructions**: Include specific steps and expected output
4. **No Context**: Explain why this documentation exists
5. **Over-Linking**: 3-5 key links is usually enough
6. **Inconsistent Format**: Follow templates for similar doc types
7. **Missing Ownership**: Know who maintains what
8. **Broken Links**: Periodically check and fix internal links
## Examples of Great Documentation
Look for these characteristics in well-documented knowledge:
✓ Clear purpose stated upfront
✓ Specific examples and code
✓ Step-by-step instructions when applicable
✓ Links to prerequisites and related docs
✓ Date or version information
✓ Clear ownership/maintainer
✓ Table of contents for long docs
✓ Searchable keywords in title and headings
## Tools & Templates
See the `templates/` directory for:
- How-To template
- Decision Record template
- FAQ template
- Meeting Summary template
- Learning Document template
- Process Documentation template

213
skills/knowledge-capture/reference/documentation-types.md Normal file
View File

@@ -0,0 +1,213 @@
# Knowledge Capture - Documentation Types Guide
This guide explains the different documentation types that Knowledge Capture can create and when to use each one.
## Documentation Types
### 1. How-To Guides
**Purpose:** Step-by-step instructions for accomplishing a specific task
**Structure:**
- Title (action-oriented, e.g., "How to Set Up OAuth")
- Overview (what this guide covers and why it matters)
- Prerequisites (knowledge, tools, or access needed)
- Numbered Steps (clear, sequential instructions)
- Troubleshooting (common issues and solutions)
- Related Resources (links to other documentation)
**Example Context:**
```
Conversation about: Implementing authentication flow
→ Knowledge Capture suggests: How-To Guide
→ Output: "How to Implement OAuth 2.0 in Node.js"
```
**Best Practices:**
- Keep steps atomic (one action per step)
- Include expected outputs/confirmations
- Add screenshots or examples when possible
- Test instructions before publishing
---
### 2. Decision Records
**Purpose:** Document important decisions and their rationale
**Structure:**
- Title (clear decision statement)
- Date & Context (when and why this decision was needed)
- Problem Statement (what needed to be decided)
- Options Considered (alternatives with pros/cons)
- Decision (what was decided and why)
- Consequences (impacts and follow-ups)
- Related Decisions (decisions that connect to this one)
**Example Context:**
```
Conversation about: Choosing between microservices and monolith
→ Knowledge Capture suggests: Decision Record
→ Output: "Architecture Decision: Monolithic vs. Microservices"
```
**Best Practices:**
- Make decisions explicit and documented
- Include options you rejected and why
- Document impacts as they become clear
- Revisit periodically to validate decisions
---
### 3. FAQ Documents
**Purpose:** Provide quick answers to commonly asked questions
**Structure:**
- Topic Title (the subject area)
- Questions (organized by category or importance)
- Answers (clear, concise, with examples)
- See Also (links to related topics)
**Example Context:**
```
Conversation about: Common questions about API usage
→ Knowledge Capture suggests: FAQ
→ Output: "API Integration FAQ"
```
**Best Practices:**
- Order by frequency and importance
- Keep answers concise but complete
- Include code examples where relevant
- Link to detailed documentation for deep dives
---
### 4. Meeting Summaries
**Purpose:** Capture outcomes from meetings
**Structure:**
- Meeting Details (date, attendees, purpose)
- Key Decisions (what was decided)
- Action Items (who, what, when)
- Discussion Summary (what was discussed)
- Next Steps (what happens next)
- Related Materials (linked documents)
**Example Context:**
```
Conversation from: Product planning meeting
→ Knowledge Capture suggests: Meeting Summary
→ Output: "Q4 Planning Meeting - November 9, 2025"
```
**Best Practices:**
- Capture decisions and action items immediately
- Make action items specific and assignable
- Link to relevant documentation
- Distribute summary within 24 hours
---
### 5. Learning Documents
**Purpose:** Preserve knowledge and learning from experiences
**Structure:**
- Situation (context and background)
- What Happened (the story or event)
- Key Learnings (takeaways and insights)
- Best Practices (applicable lessons)
- Resources (further reading)
- Related Learning (connected documents)
**Example Context:**
```
Conversation about: Why a deployment went wrong
→ Knowledge Capture suggests: Learning Document
→ Output: "Lessons from November Production Incident"
```
**Best Practices:**
- Focus on patterns and principles
- Be honest about mistakes
- Emphasize what you'd do differently
- Make it practical and actionable
---
### 6. Process Documentation
**Purpose:** Document standard processes and workflows
**Structure:**
- Process Name (clear, action-oriented)
- Purpose (why this process exists)
- Scope (when and where it applies)
- Responsibilities (who does what)
- Steps (detailed workflow)
- Approval (if needed)
- Review Schedule (how often to revisit)
**Example Context:**
```
Conversation about: How code reviews work in the team
→ Knowledge Capture suggests: Process Documentation
→ Output: "Code Review Process"
```
**Best Practices:**
- Keep current with team changes
- Include decision points and escalation paths
- Make roles and responsibilities clear
- Version and date your processes
---
## Selection Guidance
Use this flowchart to determine the best documentation type:
```
Question: What are you capturing?
├─ A task someone needs to do?
│ └─ How-To Guide
│
├─ A decision that was made?
│ └─ Decision Record
│
├─ Repeated questions?
│ └─ FAQ
│
├─ What happened in a meeting?
│ └─ Meeting Summary
│
├─ An experience to learn from?
│ └─ Learning Document
│
└─ A repeated workflow?
└─ Process Documentation
```
---
## Linking Documentation
Once created, ensure new documentation is discoverable:
1. **Hub Pages**: Add to relevant index or category pages
2. **Backlinks**: Link from source materials
3. **Tags**: Use consistent tagging for search
4. **Cross-references**: Link to related documentation
## Best Practices Across All Types
- **Consistent Format**: Follow the structure for your doc type
- **Clear Titles**: Use descriptive, searchable titles
- **Dated/Versioned**: Include dates, especially for time-sensitive info
- **Author/Owner**: Know who to ask about updates
- **Regular Review**: Schedule periodic reviews to keep current
- **Examples**: Include concrete examples and templates

102
skills/meeting-intelligence/SKILL.md Normal file
View File

@@ -0,0 +1,102 @@
---
name: meeting-intelligence
description: Prepare for meetings by gathering context and creating comprehensive agendas
---
## Overview
The Meeting Intelligence skill prepares you for productive meetings by automatically gathering relevant context, analyzing past interactions, and creating comprehensive meeting agendas. It helps ensure you enter meetings informed and prepared.
## When to Use
Use this skill when you need to:
- Prepare for important meetings
- Gather context about attendees and topics
- Create comprehensive meeting agendas
- Review past interactions with participants
- Identify potential discussion points and blockers
- Prepare background materials for meetings
## Features
- **Context Gathering**: Automatically collects relevant documentation and past interactions
- **Attendee Analysis**: Gathers information about meeting participants
- **Agenda Creation**: Generates structured meeting agendas with timing
- **Background Materials**: Compiles reference materials and context documents
- **Risk/Blocker Identification**: Surfaces potential issues to address
- **Decision Tracking**: Monitors previously made decisions relevant to the meeting
## Requirements
- **Notion API Access**: For retrieving documentation and meeting history
- **Calendar Integration (Optional)**: To pull meeting details
- **Context Database**: Notion database with relevant background information
- **Team Database**: Directory of team members and their expertise areas
## Implementation Details
This skill leverages Notion as a knowledge base to:
1. Search relevant documentation and past meetings
2. Analyze attendee profiles and expertise areas
3. Identify agenda items based on historical context
4. Create structured agenda pages in Notion
5. Compile background materials and references
6. Track follow-up items from previous meetings
### Meeting Preparation Workflow
```
Meeting Request
↓
Extract Meeting Details
↓
Search Relevant Context
↓
Analyze Attendees
↓
Identify Agenda Items
↓
Compile Background Materials
↓
Create Comprehensive Agenda
↓
Output: Prepared Meeting Document
```
## Example Use Cases
1. **Executive Status Meeting**
- Gathers recent project updates, metrics, and blockers
- Creates agenda aligned with executive focus areas
- Prepares data and trend analysis
2. **Client Meeting**
- Compiles project history, agreements, and past discussions
- Identifies open items and next steps
- Creates agenda addressing client concerns
3. **One-on-One**
- Gathers feedback, performance notes, and career development info
- Creates agenda with growth and feedback discussion
4. **Cross-functional Planning**
- Collects input from all stakeholders
- Identifies dependencies and potential conflicts
- Creates comprehensive coordination agenda
## Configuration
```env
NOTION_API_TOKEN=your_token_here
MEETING_DATABASE_ID=your_database_id
CONTEXT_DATABASE_ID=your_context_database_id
ATTENDEE_DATABASE_ID=your_attendee_database_id
```
## See Also
- [Knowledge Capture](/skills/knowledge-capture) - For documenting meeting outcomes
- [Research Documentation](/skills/research-documentation) - For background research
- [Spec to Implementation](/skills/spec-to-implementation) - For meeting-driven implementation planning
- [Notion Database Documentation](https://developers.notion.com/reference/database)

41
skills/meeting-intelligence/evaluations/README.md Normal file
View File

@@ -0,0 +1,41 @@
# Meeting Intelligence - Evaluation Scenarios
Test scenarios for validating meeting preparation and agenda creation.
## Running Evaluations
1. Provide meeting context (topic, attendees, date)
2. Request meeting preparation
3. Verify output includes:
- Comprehensive agenda with timing
- Relevant background context
- Prepared materials
- Discussion talking points
## Evaluation Criteria
**Agenda Quality**
- Clear objectives for each item
- Realistic timing allocations
- Logical flow and progression
- All necessary topics covered
**Context Gathering**
- Relevant background retrieved
- Stakeholder information included
- Previous decisions/discussions referenced
- Potential issues surfaced
**Practicality**
- Agenda ready to use immediately
- Materials referenced are accessible
- Talking points are specific
- Decision points clearly identified
## Test Scenarios Included
- Executive status meeting
- Cross-functional planning session
- 1-on-1 conversation prep
- Client meeting preparation
- Sprint planning meeting

159
skills/meeting-intelligence/reference/agenda-structure-guide.md Normal file
View File

@@ -0,0 +1,159 @@
# Meeting Intelligence - Agenda Structure Guide
## Professional Agenda Format
A well-structured meeting agenda serves as both a preview for participants and a guide for the meeting facilitator.
### Essential Components
**1. Header Information**
```
Meeting: [Clear, Descriptive Title]
Date: [Date and Time with Timezone]
Duration: [e.g., 60 minutes]
Location/Link: [Physical location or Zoom link]
Organizer: [Who's running the meeting]
```
**2. Purpose Statement**
Clear, 1-2 sentence description of why this meeting exists and what success looks like.
**3. Attendees**
- Required attendees with roles
- Optional attendees
- Guest speakers (if any)
**4. Pre-Read Materials**
- What should attendees review before the meeting
- Location/links to key documents
- Time to review suggested (e.g., 10 minutes)
### Agenda Items Template
For each agenda item, include:
```
## [Time] - [Topic Title]
**Purpose:** Why are we discussing this?
**Key Questions:** What do we need to decide/understand?
**Owner:** Who is leading this discussion?
**Expected Outcome:** What should we have when done?
**Materials:**
- [Link to relevant doc]
- [Link to data/metrics]
```
### Timing Guidelines
**Total meeting time: 60 minutes**
| Duration | Time per Item | Type | Example |
|----------|--------------|------|---------|
| 30 min | 5-7 min | Status update | Updates from team |
| 60 min | 10-15 min | Decision | Technical approach choice |
| 90 min | 15-20 min | Deep dive | Specification review |
| 120 min | 20-30 min | Planning | Sprint planning |
**Rule of Thumb:** Each agenda item should take 30% longer than you think to avoid rushing.
### Different Meeting Types
#### Executive Status Meeting
```
- Quick wins/metrics (5 min)
- Blockers/risks (10 min)
- Key decisions needed (10 min)
- Q&A (5 min)
```
#### Sprint Planning
```
- Goal review & context (10 min)
- Backlog review (20 min)
- Capacity planning (15 min)
- Sprint goal finalization (10 min)
- Q&A (5 min)
```
#### 1-on-1 Conversation
```
- How are you doing? (5 min)
- Work update (10 min)
- One development area (10 min)
- Support/help needed (5 min)
```
#### Cross-functional Kickoff
```
- Project overview (10 min)
- Success criteria (10 min)
- Team roles (10 min)
- Timeline/milestones (10 min)
- Q&A (10 min)
```
### Internal Pre-Read vs. External Agenda
**Internal Pre-Read (Team Only)**
- Honest assessment and context
- Sensitive business information
- Detailed background
- Strategic rationale
- Concerns and risks
**External Agenda (All Participants)**
- Focused objectives
- Clear decisions needed
- Professional tone
- Time allocations
- Preparation requirements
### Creating Effective Agendas
**Do:**
✓ Include time allocations
✓ State clear objectives for each item
✓ Link to relevant materials
✓ Designate topic owners
✓ Leave buffer time
✓ End with clear next steps
**Don't:**
✗ Create vague agenda items ("Miscellaneous")
✗ Overload meetings with too many topics
✗ Forget time allocations
✗ Create agendas without objectives
✗ Ignore pre-read materials
✗ Skip attendee confirmations
### Post-Meeting Update
After the meeting:
```
## Decisions Made
- [Decision 1 and rationale]
- [Decision 2 and rationale]
## Action Items
| Owner | Task | Deadline |
|-------|------|----------|
| | | |
## Next Meeting
- Date/Time:
- Purpose:
- Tentative Topics:
```
### Agenda Best Practices
1. **Share Early**: Send 24+ hours before meeting
2. **Collaborative**: Encourage attendees to suggest additions
3. **Time-Boxed**: Be realistic about timing
4. **Prioritized**: Put critical items first
5. **Flexible**: Build in buffer for important discussions
6. **Connected**: Link to related materials and decisions
7. **Documented**: Keep for future reference

117
skills/research-documentation/SKILL.md Normal file
View File

@@ -0,0 +1,117 @@
---
name: research-documentation
description: Research topics and document findings in Notion with organized structure and sources
---
## Overview
The Research Documentation skill automates the process of researching topics and capturing findings in a well-organized Notion database. It streamlines research by structuring information, tracking sources, and connecting related findings.
## When to Use
Use this skill when you need to:
- Research complex topics and document findings
- Compile competitive analysis or market research
- Create literature reviews or research summaries
- Build knowledge bases around specific topics
- Track sources and citations
- Organize research across multiple domains
- Create research reports with sourced information
## Features
- **Structured Research Capture**: Automatically organizes research findings with proper hierarchy
- **Source Tracking**: Maintains complete source attribution and citations
- **Topic Organization**: Categorizes findings by theme and relevance
- **Cross-referencing**: Connects related research across topics
- **Evidence Collection**: Captures quotes, data, and supporting evidence
- **Research Timeline**: Tracks how understanding evolved during research
## Requirements
- **Notion API Access**: For creating and updating research documentation
- **Research Database**: Notion database structure for organizing findings
- **Web Access**: For gathering information from online sources
- **Citation Format Preference**: Configured citation style (APA, MLA, Chicago, etc.)
## Implementation Details
This skill orchestrates research workflows by:
1. Breaking down research topics into focused areas
2. Gathering information from multiple sources
3. Analyzing and synthesizing findings
4. Organizing findings with proper attribution
5. Creating relationships between related research
6. Generating summary documents and reports
### Research Documentation Workflow
```
Research Topic/Question
↓
Break into Research Areas
↓
Gather Information
↓
Analyze & Synthesize
↓
Extract Key Findings
↓
Organize with Sources
↓
Create Notion Documentation
↓
Output: Research Summary
```
## Example Use Cases
1. **Competitive Analysis**
- Research competitors and market landscape
- Document features, pricing, and positioning
- Create competitive comparison matrix
2. **Technology Evaluation**
- Research framework/tool options
- Document pros, cons, and use cases
- Create evaluation report with recommendations
3. **Domain Knowledge Building**
- Research industry best practices
- Document standards and approaches
- Create reference guide for team
4. **Literature Review**
- Research academic papers on topic
- Summarize findings and arguments
- Create annotated bibliography
5. **Market Research**
- Gather market size and trends
- Document customer needs
- Create market analysis report
## Configuration
```env
NOTION_API_TOKEN=your_token_here
RESEARCH_DATABASE_ID=your_database_id
SOURCES_DATABASE_ID=your_sources_database_id
CITATION_FORMAT=APA
```
## Citation Formats Supported
- APA
- MLA
- Chicago Style
- Harvard
- IEEE
## See Also
- [Knowledge Capture](/skills/knowledge-capture) - For documenting discussions and insights
- [Meeting Intelligence](/skills/meeting-intelligence) - For research-informed meeting prep
- [Spec to Implementation](/skills/spec-to-implementation) - For research-based implementation planning
- [Notion API Documentation](https://developers.notion.com)

28
skills/research-documentation/evaluations/README.md Normal file
View File

@@ -0,0 +1,28 @@
# Research Documentation - Evaluation Scenarios
Test scenarios for validating research quality, sourcing, and documentation formats.
## Evaluation Focus
- **Comprehensiveness**: Are all aspects of the research topic covered?
- **Sourcing**: Are all claims backed by sources? Are citations proper?
- **Accuracy**: Is the information accurate and up-to-date?
- **Format**: Does the output match the requested format?
- **Accessibility**: Is the research understandable to the target audience?
## Test Scenario Types
1. **Quick Brief** - Fast research with key findings
2. **Comparison Analysis** - Evaluating multiple options
3. **Comprehensive Report** - Deep-dive research documentation
4. **Market Research** - Industry and competitive analysis
5. **Technical Investigation** - Product/technology research
## Success Criteria
✓ All major sources cited with proper attribution
✓ Format requirements met (length, structure)
✓ Key findings clearly stated
✓ Comparisons fair and balanced
✓ Recommendations supported by research
✓ Ready for stakeholder presentation

168
skills/research-documentation/reference/format-guide.md Normal file
View File

@@ -0,0 +1,168 @@
# Research Documentation - Format Selection Guide
Choose the right format for your research output based on scope, complexity, and intended audience.
## Quick Brief
**Best for:** Initial findings, quick summaries, stakeholder updates
**Length:** 1-2 pages
**Structure:**
- Question/Topic
- Key Findings (3-5 bullet points)
- Sources Used
- Next Steps
**Example Use:**
"Should we adopt React or Vue?"
→ Quick Brief comparing both with recommendation
---
## Comparison Matrix
**Best for:** Evaluating multiple options against criteria
**Structure:**
```
| Criteria | Option A | Option B | Option C |
|----------|----------|----------|----------|
| Cost | $ | $$ | $$$ |
| Learning Curve | Easy | Medium | Hard |
| ... | | | |
```
**Example Use:**
Technology evaluation, vendor comparison, feature analysis
---
## Research Summary
**Best for:** Balanced overview of a topic with findings and recommendations
**Length:** 2-4 pages
**Structure:**
- Overview
- Key Findings
- Analysis & Synthesis
- Recommendations
- Sources & Citations
**Example Use:**
Market trends, industry analysis, competitive landscape
---
## Comprehensive Report
**Best for:** Deep dives, detailed analysis, archival
**Length:** 5-20 pages
**Structure:**
- Executive Summary
- Introduction & Context
- Methodology
- Findings (organized by theme)
- Analysis & Implications
- Recommendations
- Appendices
- References
**Example Use:**
Product research, technical investigation, business analysis
---
## Decision Memo
**Best for:** Research that informs a specific decision
**Structure:**
- Decision Required
- Background
- Research Findings
- Options with Trade-offs
- Recommendation
- Implementation Steps
**Example Use:**
Technology selection, resource allocation, strategic direction
---
## Selection Flowchart
```
What are you researching?
├─ Quick answer needed?
│ └─ Quick Brief
│
├─ Comparing options?
│ └─ Comparison Matrix
│
├─ Balanced overview?
│ └─ Research Summary
│
├─ Supporting a decision?
│ └─ Decision Memo
│
└─ Comprehensive documentation?
└─ Comprehensive Report
```
---
## Format Standards
**Citation Style**
- APA, MLA, Chicago, or Harvard
- Include author, date, source
- Use consistent format throughout
**Sourcing**
- Link to actual sources
- Note access date for web content
- Mark primary vs. secondary sources
- Include direct quotes with attribution
**Structure**
- Clear headings (H2, H3, etc.)
- Short paragraphs (2-4 sentences)
- Bullet points for lists
- Tables for comparisons
**Visual Elements**
- Include relevant charts/graphs
- Use consistent formatting
- Add images/screenshots with captions
- Label tables and figures clearly
---
## Examples by Format
### Example 1: Quick Brief
**Topic:** Headless CMS Options
**Sources:** 2 tools evaluated
**Decision Time:** 2 hours research
**Outcome:** Recommendation selected in 1 day
### Example 2: Comparison Matrix
**Topic:** Email Service Providers
**Sources:** 4 vendors evaluated
**Decision Time:** 4 hours research
**Outcome:** Feature matrix drives selection
### Example 3: Research Summary
**Topic:** AI Model Options for Product
**Sources:** 10+ sources reviewed
**Decision Time:** 8 hours research
**Outcome:** Technical team briefed, approach chosen
### Example 4: Comprehensive Report
**Topic:** Market Analysis for New Product
**Sources:** 20+ sources, interviews
**Decision Time:** 40+ hours research
**Outcome:** Business case developed, investment approved

138
skills/spec-to-implementation/SKILL.md Normal file
View File

@@ -0,0 +1,138 @@
---
name: spec-to-implementation
description: Parse specifications and create implementation plans with task tracking in Notion
---
## Overview
The Spec-to-Implementation skill transforms project specifications into detailed implementation plans with comprehensive task breakdowns, timeline estimates, and dependency tracking in Notion. It bridges the gap between requirements and execution.
## When to Use
Use this skill when you need to:
- Convert project specifications into actionable implementation plans
- Break down complex features into implementable tasks
- Create detailed project timelines with estimates
- Identify dependencies and critical path items
- Generate task checklists with ownership and deadlines
- Track implementation progress in Notion
- Create architectural and technical specifications from requirements
## Features
- **Smart Requirement Parsing**: Automatically extracts requirements and acceptance criteria
- **Task Decomposition**: Breaks specifications into atomic, implementable tasks
- **Dependency Mapping**: Identifies and visualizes task dependencies
- **Effort Estimation**: Provides time estimates for tasks and milestones
- **Ownership Assignment**: Creates task assignments with clarity
- **Progress Tracking**: Sets up Notion databases for implementation tracking
- **Risk Identification**: Highlights potential implementation risks and blockers
## Requirements
- **Notion API Access**: For creating implementation plans and task databases
- **Specification Format**: Clear specification documents (markdown, PDFs, or text)
- **Team Database**: Directory of team members and skills (optional but recommended)
- **Project Template**: Pre-configured Notion template for consistency
## Implementation Details
This skill transforms specifications through a systematic process:
1. Parse specification document and extract requirements
2. Break requirements into user stories and tasks
3. Identify technical dependencies and blockers
4. Create detailed implementation plan with phases
5. Estimate effort for each task
6. Assign ownership and set deadlines
7. Create tracking structure in Notion
8. Generate project dashboard and status reports
### Spec-to-Implementation Workflow
```
Specification Document
↓
Extract Requirements
↓
Break into User Stories
↓
Decompose into Tasks
↓
Identify Dependencies
↓
Estimate Effort
↓
Assign Ownership
↓
Create Notion Plan
↓
Output: Implementation Roadmap
```
## Example Use Cases
1. **Feature Implementation**
- Input: Feature specification with requirements
- Output: Task breakdown with timeline and ownership
- Tracks: Progress dashboard in Notion
2. **Product Launch**
- Input: Product specification and launch requirements
- Output: Launch plan with phases, dependencies, and critical path
- Tracks: Multi-team coordination and milestones
3. **System Migration**
- Input: Migration specification and technical requirements
- Output: Detailed migration plan with phases
- Tracks: Data mapping, system cutover, and rollback procedures
4. **Infrastructure Project**
- Input: Infrastructure design specification
- Output: Implementation plan with testing and deployment phases
- Tracks: Build, test, and deployment checkpoints
5. **API Development**
- Input: API specification and endpoint requirements
- Output: Development tasks with testing and documentation
- Tracks: Development progress and integration milestones
## Task Hierarchy
```
Epic (Feature)
├── User Story 1
│ ├── Task 1.1 (Backend)
│ ├── Task 1.2 (Frontend)
│ └── Task 1.3 (Testing)
├── User Story 2
│ └── [Tasks...]
└── Acceptance Criteria
```
## Configuration
```env
NOTION_API_TOKEN=your_token_here
PROJECT_DATABASE_ID=your_database_id
TASK_DATABASE_ID=your_task_database_id
TEAM_DATABASE_ID=your_team_database_id
ESTIMATE_UNIT=hours
```
## Estimate Units
Supported time estimate formats:
- Hours
- Story Points
- Days
- Weeks
- Planning Poker values (1, 2, 3, 5, 8, 13, 21)
## See Also
- [Knowledge Capture](/skills/knowledge-capture) - For documenting design decisions
- [Meeting Intelligence](/skills/meeting-intelligence) - For kickoff meeting preparation
- [Research Documentation](/skills/research-documentation) - For technology research
- [Notion Database Documentation](https://developers.notion.com)
- [Agile Task Management Best Practices](https://developers.notion.com)

46
skills/spec-to-implementation/evaluations/README.md Normal file
View File

@@ -0,0 +1,46 @@
# Spec-to-Implementation - Evaluation Scenarios
Test scenarios for validating specification parsing and implementation plan generation.
## Evaluation Criteria
**Requirement Extraction**
- All functional requirements identified
- Non-functional requirements documented
- Acceptance criteria captured
- Dependencies clearly stated
**Task Breakdown**
- Specifications decomposed into atomic tasks
- Task sizing appropriate (1-2 days each)
- Technical dependencies mapped
- Parallel work opportunities identified
**Estimation**
- Effort estimates realistic
- Timeline achieves project goals
- Buffer time included for unknowns
- Risk factors considered
**Tracking**
- Implementation plan is actionable
- Progress metrics are trackable
- Milestones clearly defined
- Links to specification maintained
## Test Scenario Types
1. **Feature Implementation** - New feature specification to implementation plan
2. **API Development** - API specification with endpoint breakdown
3. **System Migration** - Migration specification with phased approach
4. **Product Launch** - Multi-component launch planning
5. **Infrastructure Project** - Technical infrastructure setup
## Success Indicators
✓ All requirements addressed in task list
✓ Tasks are specific and actionable
✓ Timeline is realistic
✓ Dependencies are clear
✓ Implementation is trackable
✓ Risks identified and mitigation planned

240
skills/spec-to-implementation/reference/task-breakdown-guide.md Normal file
View File

@@ -0,0 +1,240 @@
# Spec to Implementation - Task Breakdown Guide
How to decompose specifications into well-structured, implementable tasks.
## Task Hierarchy
```
Specification Document
├── Requirement 1
│ ├── User Story 1.1
│ │ ├── Task 1.1.1 (Backend)
│ │ ├── Task 1.1.2 (Frontend)
│ │ └── Task 1.1.3 (Testing)
│ └── User Story 1.2
│ └── [Tasks...]
└── Requirement 2
└── [User Stories and Tasks...]
```
## Task Properties
Each task should have:
| Property | Purpose | Example |
|----------|---------|---------|
| **Title** | Clear, action-oriented | "Implement user authentication endpoint" |
| **Description** | What, why, how | Details of implementation approach |
| **Acceptance Criteria** | How to know it's done | "Users can log in with email/password" |
| **Estimate** | Effort required | "5 story points" or "8 hours" |
| **Owner** | Who's doing it | "Alex Chen" |
| **Dependencies** | What must happen first | "Database schema finalized" |
| **Priority** | Urgency | "P0 - Blocking", "P1 - Critical", etc. |
## Task Sizing
**Too Large (> 3 days)**
- Hard to estimate accurately
- Difficult to track progress
- Risk of getting blocked
**Right Size (1-2 days)**
- Concrete and actionable
- Progress visible daily
- Easier to unblock
**Too Small (< 2 hours)**
- Overhead from task management
- Discourages good estimates
- Creates task clutter
## Task Types
### Backend Implementation
```
Task: Implement [feature] endpoint
Acceptance Criteria:
- [ ] Endpoint accepts [inputs]
- [ ] Returns [format] with [fields]
- [ ] Validates [constraints]
- [ ] Handles [error cases]
- [ ] Tests cover [coverage level]%
```
### Frontend Implementation
```
Task: Build [component/page]
Acceptance Criteria:
- [ ] Component renders [expected layout]
- [ ] Responds to [user interactions]
- [ ] Displays [content] from API
- [ ] Works on [screen sizes]
- [ ] Accessible (WCAG [level])
```
### Database/Data
```
Task: Create [schema/migration]
Acceptance Criteria:
- [ ] Schema supports [use cases]
- [ ] Indexes created for [queries]
- [ ] Migration handles [data]
- [ ] Rollback plan documented
- [ ] Performance tested
```
### Testing
```
Task: Test [feature/component]
Acceptance Criteria:
- [ ] Unit tests: [X]% coverage
- [ ] Integration tests for [scenarios]
- [ ] End-to-end tests for [flows]
- [ ] Performance tests meet [targets]
- [ ] Documented edge cases
```
### Documentation
```
Task: Document [feature/API]
Acceptance Criteria:
- [ ] API documentation complete
- [ ] Usage examples included
- [ ] Edge cases documented
- [ ] Links to related docs added
- [ ] Reviewed and approved
```
## Dependency Mapping
**Identify blocking dependencies:**
```
Auth Implementation (5 days)
├── Database schema (2 days) ← Must happen first
├── API endpoint (3 days) ← Depends on schema
├── Frontend UI (2 days) ← Depends on endpoint
└── Testing (2 days) ← Depends on frontend
```
**Critical Path:** Schema → Endpoint → Frontend → Testing (11 days)
**Parallel Work:** Multiple features can start once dependencies met
## Effort Estimation
**Estimation Techniques:**
1. **Story Points** (Fibonacci: 1, 2, 3, 5, 8, 13)
- Relative sizing
- Good for iterative planning
- Accounts for uncertainty
2. **Hours** (for precise tracking)
- 4-6 hours = Small task
- 8-16 hours = Medium task
- 16+ hours = Break down further
3. **Days** (for roadmapping)
- 1 day = Sprint task
- 2-3 days = Normal task
- 4+ days = Risky, reconsider
## Acceptance Criteria Format
**Good Acceptance Criteria:**
```
Given [context]
When [action happens]
Then [expected result]
```
**Example:**
```
Given user is on the login page
When they enter email and click submit without password
Then they see error "Password is required"
```
## Common Decomposition Patterns
### By Component
- Task 1: Implement backend service
- Task 2: Build UI component
- Task 3: Integrate frontend to backend
- Task 4: Test end-to-end
### By Feature Slice
- Task 1: Happy path implementation
- Task 2: Error handling
- Task 3: Edge cases
- Task 4: Performance optimization
### By Layer
- Task 1: Database layer
- Task 2: API layer
- Task 3: Frontend layer
- Task 4: Integration & testing
### By Priority
- Task 1: MVP features
- Task 2: Core features
- Task 3: Nice-to-haves
- Task 4: Future enhancements
## Red Flags
⚠️ **Task is too vague**
- "Fix authentication" → Break down to specific changes
⚠️ **Task has unclear owner**
- Ensure one person is clearly responsible
⚠️ **Task has no acceptance criteria**
- Add specific, measurable completion definition
⚠️ **Task is estimated at 13+ points**
- Break into smaller tasks
⚠️ **Task has unidentified dependencies**
- List all blockers explicitly
⚠️ **Task depends on another task being done**
- Create clear sequence or parallelize where possible
## Task Lifecycle
```
Spec Analysis
↓
Task Identification
↓
Dependency Mapping
↓
Prioritization & Sequencing
↓
Estimation
↓
Assignment
↓
Implementation (with daily progress)
↓
Review & Testing
↓
Completion & Documentation
```
## Documentation in Task Manager
Each task should link to:
- [ ] Original specification
- [ ] Related tasks
- [ ] Design documentation
- [ ] Test cases
- [ ] Code review URL
- [ ] Merged PR/commit