diff --git a/skills/.curated/notion-knowledge-capture/LICENSE.txt b/skills/.curated/notion-knowledge-capture/LICENSE.txt new file mode 100644 index 0000000..0871708 --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/LICENSE.txt @@ -0,0 +1,7 @@ +Copyright 2025 Notion Labs, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/skills/.curated/notion-knowledge-capture/SKILL.md b/skills/.curated/notion-knowledge-capture/SKILL.md new file mode 100644 index 0000000..577b704 --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/SKILL.md @@ -0,0 +1,12 @@ +--- +name: notion-knowledge-capture +description: Capture conversations and discussions into structured Notion pages; use when asked to save, document, or capture knowledge to Notion wiki or database. +--- + +# Knowledge Capture + +- Extract key information from conversation context +- Structure into appropriate format (concept, how-to, decision record, FAQ) +- Save to Notion using `Notion:notion-create-pages` +- Link from hub pages to ensure discoverability +- See reference/ for database schemas and content type templates diff --git a/skills/.curated/notion-knowledge-capture/evaluations/README.md b/skills/.curated/notion-knowledge-capture/evaluations/README.md new file mode 100644 index 0000000..e140f31 --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/evaluations/README.md @@ -0,0 +1,95 @@ +# Knowledge Capture Skill Evaluations + +Evaluation scenarios for testing the Knowledge Capture skill across different Codex models. + +## Purpose + +These evaluations ensure the Knowledge Capture skill: +- Correctly identifies content types (how-to guides, FAQs, decision records, wikis) +- Extracts relevant information from conversations +- Structures content appropriately for each type +- Searches and places content in the right Notion location +- Works consistently across Haiku, Sonnet, and Opus + +## Evaluation Files + +### conversation-to-wiki.json +Tests capturing conversation content as a how-to guide for the team wiki. + +**Scenario**: Save deployment discussion to wiki +**Key Behaviors**: +- Extracts steps, gotchas, and best practices from conversation +- Identifies content as How-To Guide +- Structures with proper sections (Overview, Prerequisites, Steps, Troubleshooting) +- Searches for team wiki location +- Preserves technical details (commands, configs) + +### decision-record.json +Tests capturing architectural or technical decisions with full context. + +**Scenario**: Document database migration decision +**Key Behaviors**: +- Extracts decision context, alternatives, and rationale +- Follows decision record structure (Context, Decision, Alternatives, Consequences) +- Captures both selected and rejected options with reasoning +- Places in decision log or ADR database +- Links to related technical documentation + +## Running Evaluations + +1. Enable the `knowledge-capture` skill +2. Submit the query from the evaluation file +3. Provide conversation context as specified +4. Verify all expected behaviors are met +5. Check success criteria for quality +6. Test with Haiku, Sonnet, and Opus + +## Expected Skill Behaviors + +Knowledge Capture evaluations should verify: + +### Content Extraction +- Accurately captures key points from conversation context +- Preserves specific technical details, not generic placeholders +- Maintains context and nuance from discussion + +### Content Type Selection +- Correctly identifies appropriate content type (how-to, FAQ, decision record, wiki page) +- Uses matching structure from reference documentation +- Applies proper Notion markdown formatting + +### Notion Integration +- Searches for appropriate target location (wiki, decision log, etc.) +- Creates well-structured pages with clear titles +- Uses proper parent placement +- Includes discoverable titles and metadata + +### Quality Standards +- Content is actionable and future-reference ready +- Technical accuracy is preserved +- Organization aids discoverability +- Formatting enhances readability + +## Creating New Evaluations + +When adding Knowledge Capture evaluations: + +1. **Use realistic conversation content** - Include actual technical details, decisions, or processes +2. **Test different content types** - How-to guides, FAQs, decision records, meeting notes, learnings +3. **Vary complexity** - Simple captures vs. complex technical discussions +4. **Test discovery** - Finding the right wiki section or database +5. **Include edge cases** - Unclear content types, minimal context, overlapping categories + +## Example Success Criteria + +**Good** (specific, testable): +- "Structures content using How-To format with numbered steps" +- "Preserves exact bash commands from conversation" +- "Creates page with title format 'How to [Action]'" +- "Places in Engineering Wiki → Deployment section" + +**Bad** (vague, untestable): +- "Creates good documentation" +- "Uses appropriate structure" +- "Saves to the right place" + diff --git a/skills/.curated/notion-knowledge-capture/evaluations/conversation-to-wiki.json b/skills/.curated/notion-knowledge-capture/evaluations/conversation-to-wiki.json new file mode 100644 index 0000000..a7e0c7f --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/evaluations/conversation-to-wiki.json @@ -0,0 +1,31 @@ +{ + "name": "Save Conversation to Wiki", + "skills": ["knowledge-capture"], + "query": "Save this conversation about deploying our application to production to the team wiki", + "context": "Preceding conversation contains discussion about deployment process, including steps, gotchas, and best practices", + "expected_behavior": [ + "Extracts key information from conversation context (deployment steps, gotchas, best practices)", + "Identifies content type as How-To Guide based on procedural nature", + "Structures content using How-To structure: Overview → Prerequisites → Steps (numbered) → Verification → Troubleshooting → Related", + "Organizes information into clear sections with proper headings", + "Includes specific commands, configurations, or examples from conversation", + "Adds context about why/when to use this process in Overview section", + "Notes common issues and solutions mentioned in discussion in Troubleshooting section", + "Uses Notion:notion-search to find team wiki location or asks user", + "Creates page using Notion:notion-create-pages with structured content and appropriate parent", + "Uses clear, descriptive title like 'How to Deploy to Production'", + "Applies Notion markdown formatting (headings, code blocks, bullets)", + "Suggests tags/categories for discoverability if wiki database" + ], + "success_criteria": [ + "Content is structured using How-To format from SKILL.md content types", + "Key points from conversation are captured accurately (not generic)", + "Information is organized with proper Notion markdown (##, ###, bullets, code blocks)", + "Specific technical details (commands, configs) are preserved from conversation", + "Document is written for future reference with clear step-by-step instructions", + "Title is searchable and descriptive (e.g., 'How to Deploy to Production')", + "Page is placed in appropriate wiki location (general wiki or specific section)", + "Uses correct tool name (Notion:notion-create-pages)" + ] +} + diff --git a/skills/.curated/notion-knowledge-capture/evaluations/decision-record.json b/skills/.curated/notion-knowledge-capture/evaluations/decision-record.json new file mode 100644 index 0000000..b5ec25b --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/evaluations/decision-record.json @@ -0,0 +1,31 @@ +{ + "name": "Create Decision Record", + "skills": ["knowledge-capture"], + "query": "Document our decision to use PostgreSQL instead of MongoDB for our new service", + "context": "User has just explained the decision with rationale, options considered, and trade-offs", + "expected_behavior": [ + "Recognizes this as a decision record (architectural decision) from conversation context", + "Uses Decision structure: Context → Decision → Rationale → Options Considered (with Pros/Cons) → Consequences → Implementation", + "Extracts from context: decision made, options considered (PostgreSQL vs MongoDB), rationale, trade-offs", + "Creates document with proper structure including Date, Status (Accepted), and Deciders", + "Includes both positive and negative consequences (trade-offs) in Consequences section", + "Uses Notion:notion-search to check if decision log database exists", + "If database exists, asks whether to add there or create standalone page", + "If creating in database, fetches schema using Notion:notion-fetch and sets properties: Decision title, Date, Status, Domain (Architecture), Deciders, Impact", + "Uses Notion:notion-create-pages with parent: { data_source_id } for database or { page_id } for parent page", + "Applies proper Notion markdown formatting with sections", + "Suggests linking from architecture docs or project pages" + ], + "success_criteria": [ + "Document follows Decision structure from SKILL.md content types", + "All key sections present: Context, Decision, Rationale, Options Considered (with Pros/Cons for each), Consequences, Implementation", + "Decision is clearly stated (PostgreSQL chosen over MongoDB)", + "Options that were considered are documented with pros/cons structure", + "Rationale explains why PostgreSQL was chosen based on conversation context", + "Consequences include both positive (benefits) and negative (trade-offs)", + "If in database, properties are set correctly from schema (Decision, Date, Status: Accepted, Domain: Architecture, Impact)", + "Document is dated and has status 'Accepted'", + "Uses correct tool names (Notion:notion-search, Notion:notion-fetch, Notion:notion-create-pages)" + ] +} + diff --git a/skills/.curated/notion-knowledge-capture/examples/conversation-to-faq.md b/skills/.curated/notion-knowledge-capture/examples/conversation-to-faq.md new file mode 100644 index 0000000..1e61119 --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/examples/conversation-to-faq.md @@ -0,0 +1,226 @@ +# Example: Conversation to FAQ + +## User Request + +> "Save this conversation about deployment troubleshooting to the FAQ" + +**Context**: User just had a conversation explaining how to troubleshoot common deployment errors. + +## Conversation Summary + +The conversation covered: +1. **Question**: "Why does deployment fail with 'port already in use' error?" +2. **Answer**: Process from previous deployment still running, need to kill it +3. **Question**: "How do I find and kill the process?" +4. **Commands shared**: `lsof -ti:3000 | xargs kill -9` or use `pm2 restart app` +5. **Question**: "What about 'cannot connect to database' errors?" +6. **Answer**: Check database credentials, verify database is running, check network connectivity +7. **Best practice**: Always check logs first (`pm2 logs` or `docker logs`) + +## Workflow Execution + +### Step 1: Identify Content Type + +This is Q&A content → **FAQ Entry** format is appropriate + +### Step 2: Structure FAQ Entries + +Extract distinct Q&A pairs from conversation: + +**FAQ 1**: Port already in use error +**FAQ 2**: Cannot connect to database error +**FAQ 3**: General troubleshooting approach + +### Step 3: Determine Destination + +``` +Notion:notion-search +query: "FAQ deployment" +query_type: "internal" +``` + +Found: "Deployment FAQ" database in Engineering Docs + +``` +Notion:notion-fetch +id: "deployment-faq-database-id" +``` + +**Schema**: +- Question (title) +- Category (select): Deployment, Configuration, Troubleshooting, etc. +- Tags (multi_select) +- Last Reviewed (date) + +### Step 4: Create FAQ Entries + +**FAQ Entry 1: Port Already in Use** + +``` +Notion:notion-create-pages + +parent: { data_source_id: "collection://faq-db-uuid" } + +pages: [{ + properties: { + "Question": "Why does deployment fail with 'port already in use' error?", + "Category": "Troubleshooting", + "Tags": "deployment, errors, ports", + "date:Last Reviewed:start": "2025-10-14", + "date:Last Reviewed:is_datetime": 0 + }, + content: "## Short Answer\n\nThe deployment port (usually 3000) is still occupied by a process from a previous deployment. You need to kill the existing process before deploying again.\n\n## Detailed Explanation\n\nWhen you deploy the application, it tries to bind to a specific port (e.g., port 3000). If a previous deployment didn't shut down cleanly, that process may still be running and holding the port. This prevents the new deployment from starting.\n\n**Common causes**:\n- Previous deployment crashed without cleanup\n- Manual `node` process started and forgotten\n- PM2 or other process manager didn't restart properly\n- Multiple deployments attempted simultaneously\n\n## Solution\n\n### Option 1: Kill the process using the port\n\n```bash\n# Find and kill process on port 3000\nlsof -ti:3000 | xargs kill -9\n```\n\nReplace `3000` with your application's port number.\n\n### Option 2: If using PM2\n\n```bash\n# Restart the application\npm2 restart app\n\n# Or delete and restart\npm2 delete app\npm2 start app.js --name app\n```\n\n### Option 3: Check all node processes\n\n```bash\n# List all node processes\nps aux | grep node\n\n# Kill specific process by PID\nkill -9 \n```\n\n## Prevention\n\n1. **Use process managers**: PM2, systemd, or Docker handle cleanup automatically\n2. **Graceful shutdown**: Implement proper shutdown handlers in your app\n3. **Health checks**: Monitor if previous deployment shut down before starting new one\n\n```javascript\n// Graceful shutdown example\nprocess.on('SIGTERM', () => {\n server.close(() => {\n console.log('Server closed');\n process.exit(0);\n });\n});\n```\n\n## Verification\n\nAfter killing the process, verify the port is free:\n\n```bash\nlsof -ti:3000\n# Should return nothing if port is free\n```\n\n## Related Questions\n- How do I check what's using a port?\n- How do I configure the application port?\n- PM2 deployment best practices\n\n## Last Updated\nOctober 14, 2025" +}] +``` + +**FAQ Entry 2: Database Connection Errors** + +``` +Notion:notion-create-pages + +parent: { data_source_id: "collection://faq-db-uuid" } + +pages: [{ + properties: { + "Question": "Why do I get 'cannot connect to database' errors during deployment?", + "Category": "Troubleshooting", + "Tags": "deployment, database, errors", + "date:Last Reviewed:start": "2025-10-14", + "date:Last Reviewed:is_datetime": 0 + }, + content: "## Short Answer\n\nDatabase connection errors usually mean either the database isn't running, credentials are incorrect, or there's a network connectivity issue. Check database status, verify credentials, and test connectivity.\n\n## Detailed Explanation\n\nThe application can't establish a connection to the database during startup. This prevents the application from initializing properly.\n\n**Common causes**:\n- Database service isn't running\n- Incorrect connection credentials\n- Network connectivity issues (firewall, security groups)\n- Database host/port misconfigured\n- Database is at connection limit\n- SSL/TLS configuration mismatch\n\n## Troubleshooting Steps\n\n### Step 1: Check database status\n\n```bash\n# For local PostgreSQL\npg_isready -h localhost -p 5432\n\n# For Docker\ndocker ps | grep postgres\n\n# For MongoDB\nmongosh --eval \"db.adminCommand('ping')\"\n```\n\n### Step 2: Verify credentials\n\nCheck your `.env` or configuration file:\n\n```bash\n# Common environment variables\nDB_HOST=localhost\nDB_PORT=5432\nDB_NAME=myapp_production\nDB_USER=myapp_user\nDB_PASSWORD=***********\n```\n\nTest connection manually:\n\n```bash\n# PostgreSQL\npsql -h $DB_HOST -p $DB_PORT -U $DB_USER -d $DB_NAME\n\n# MongoDB\nmongosh \"mongodb://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME\"\n```\n\n### Step 3: Check network connectivity\n\n```bash\n# Test if port is reachable\ntelnet $DB_HOST $DB_PORT\n\n# Or using nc\nnc -zv $DB_HOST $DB_PORT\n\n# Check firewall rules (if applicable)\nsudo iptables -L\n```\n\n### Step 4: Check application logs\n\n```bash\n# PM2 logs\npm2 logs app\n\n# Docker logs\ndocker logs container-name\n\n# Application logs\ntail -f /var/log/app/error.log\n```\n\nLook for specific error messages:\n- `ECONNREFUSED`: Database not running or wrong host/port\n- `Authentication failed`: Wrong credentials\n- `Timeout`: Network/firewall issue\n- `Too many connections`: Database connection limit reached\n\n## Solutions by Error Type\n\n### Database Not Running\n\n```bash\n# Start PostgreSQL\nsudo systemctl start postgresql\n\n# Start via Docker\ndocker start postgres-container\n```\n\n### Wrong Credentials\n\n1. Reset database password\n2. Update `.env` file\n3. Restart application\n\n### Connection Limit Reached\n\n```sql\n-- Check current connections (PostgreSQL)\nSELECT count(*) FROM pg_stat_activity;\n\n-- Increase max connections\nALTER SYSTEM SET max_connections = 200;\n```\n\n### SSL/TLS Issues\n\nAdd to connection string:\n```\nssl=true&sslmode=require\n```\n\nOr disable SSL for dev:\n```\nsslmode=disable\n```\n\n## Prevention\n\n1. **Connection pooling**: Limits concurrent connections\n```javascript\npool: {\n min: 2,\n max: 10\n}\n```\n\n2. **Health checks**: Verify database before starting app\n```javascript\nconst healthCheck = async () => {\n try {\n await db.raw('SELECT 1');\n console.log('Database connected');\n } catch (err) {\n console.error('Database connection failed:', err);\n process.exit(1);\n }\n};\n```\n\n3. **Retry logic**: Auto-reconnect on temporary failures\n```javascript\nretry: {\n max: 3,\n backoff: 1000\n}\n```\n\n4. **Environment validation**: Check all required env vars exist\n```javascript\nconst required = ['DB_HOST', 'DB_PORT', 'DB_NAME', 'DB_USER', 'DB_PASSWORD'];\nfor (const key of required) {\n if (!process.env[key]) {\n throw new Error(`Missing required env var: ${key}`);\n }\n}\n```\n\n## Related Questions\n- How do I configure database connection pooling?\n- Database backup and restore procedures\n- Database performance optimization\n\n## Last Updated\nOctober 14, 2025" +}] +``` + +**FAQ Entry 3: General Troubleshooting** + +``` +Notion:notion-create-pages + +parent: { data_source_id: "collection://faq-db-uuid" } + +pages: [{ + properties: { + "Question": "What's the first thing I should check when deployment fails?", + "Category": "Troubleshooting", + "Tags": "deployment, debugging, best-practices", + "date:Last Reviewed:start": "2025-10-14", + "date:Last Reviewed:is_datetime": 0 + }, + content: "## Short Answer\n\n**Always check the logs first.** Logs contain error messages that point you directly to the problem. Use `pm2 logs`, `docker logs`, or check your application's log files.\n\n## Detailed Explanation\n\nLogs are your first and most important debugging tool. They show:\n- Exact error messages\n- Stack traces\n- Timing information\n- Configuration issues\n- Dependency problems\n\nMost deployment issues can be diagnosed and fixed by reading the logs carefully.\n\n## How to Check Logs\n\n### PM2\n\n```bash\n# View all logs\npm2 logs\n\n# View logs for specific app\npm2 logs app-name\n\n# View only errors\npm2 logs --err\n\n# Follow logs in real-time\npm2 logs --lines 100\n```\n\n### Docker\n\n```bash\n# View logs\ndocker logs container-name\n\n# Follow logs\ndocker logs -f container-name\n\n# Last 100 lines\ndocker logs --tail 100 container-name\n\n# With timestamps\ndocker logs -t container-name\n```\n\n### Application Logs\n\n```bash\n# Tail application logs\ntail -f /var/log/app/app.log\ntail -f /var/log/app/error.log\n\n# Search logs for errors\ngrep -i error /var/log/app/*.log\n\n# View logs with context\ngrep -B 5 -A 5 \"ERROR\" app.log\n```\n\n## Systematic Troubleshooting Approach\n\n### 1. Check the logs\n- Read error messages carefully\n- Note the exact error type and message\n- Check timestamps to find when error occurred\n\n### 2. Verify configuration\n- Environment variables set correctly?\n- Configuration files present and valid?\n- Paths and file permissions correct?\n\n### 3. Check dependencies\n- All packages installed? (`node_modules` present?)\n- Correct versions installed?\n- Any native module compilation errors?\n\n### 4. Verify environment\n- Required services running (database, Redis, etc.)?\n- Ports available?\n- Network connectivity working?\n\n### 5. Test components individually\n- Can you connect to database manually?\n- Can you run application locally?\n- Do health check endpoints work?\n\n### 6. Check recent changes\n- What changed since last successful deployment?\n- New dependencies added?\n- Configuration modified?\n- Environment differences?\n\n## Common Error Patterns\n\n### \"Module not found\"\n```bash\n# Solution: Install dependencies\nnpm install\n# or\nnpm ci\n```\n\n### \"Permission denied\"\n```bash\n# Solution: Fix file permissions\nchmod +x start.sh\nsudo chown -R appuser:appuser /app\n```\n\n### \"Address already in use\"\n```bash\n# Solution: Kill process on port\nlsof -ti:3000 | xargs kill -9\n```\n\n### \"Cannot connect to...\"\n```bash\n# Solution: Verify service is running and reachable\ntelnet service-host port\n```\n\n## Debugging Tools\n\n### Log Aggregation\n- **PM2**: Built-in log management\n- **Docker**: Centralized logging with log drivers\n- **ELK Stack**: Elasticsearch, Logstash, Kibana for large scale\n- **CloudWatch**: For AWS deployments\n\n### Monitoring\n- **PM2 Monit**: `pm2 monit` for real-time metrics\n- **Docker Stats**: `docker stats` for resource usage\n- **System metrics**: `top`, `htop` for CPU/memory\n\n### Network Debugging\n```bash\n# Check open connections\nnetstat -tulpn\n\n# Check specific port\nlsof -i :3000\n\n# Test connectivity\ncurl http://localhost:3000/health\n```\n\n## When to Escalate\n\nEscalate to senior team member if:\n- Error message is cryptic and not Google-able\n- Problem persists after trying obvious solutions\n- Production is affected\n- Data integrity may be compromised\n- Security-related errors\n\n## Prevention\n\n1. **Automated health checks** before deployment\n2. **Staged deployments** (dev → staging → production)\n3. **Rollback plan** ready for quick recovery\n4. **Monitoring and alerts** for early problem detection\n5. **Deployment checklist** to ensure all steps followed\n\n## Related Questions\n- How do I set up log aggregation?\n- Deployment checklist and best practices\n- How to roll back a failed deployment?\n\n## Last Updated\nOctober 14, 2025" +}] +``` + +### Step 5: Update FAQ Index + +``` +Notion:notion-fetch +id: "faq-index-page-id" +``` + +``` +Notion:notion-update-page +page_id: "faq-index-page-id" +command: "insert_content_after" +selection_with_ellipsis: "## Deployment & Troubleshooting..." +new_str: " +- Why does deployment fail with 'port already in use' error? +- Why do I get 'cannot connect to database' errors? +- What's the first thing I should check when deployment fails? +" +``` + +## Summary Provided to User + +```markdown +## FAQ Entries Created ✅ + +### Conversation Captured +Transformed deployment troubleshooting conversation into 3 comprehensive FAQ entries. + +### FAQ Entries Created + +1. **Port Already in Use Error** + - Problem: Deployment fails due to occupied port + - Solutions: Kill process, use PM2, check node processes + - Prevention: Use process managers, graceful shutdown + - Link: Port already in use FAQ + +2. **Database Connection Errors** + - Problem: Cannot connect to database during deployment + - Troubleshooting: 4-step systematic approach + - Solutions: By error type (credentials, network, limits) + - Prevention: Connection pooling, health checks, retry logic + - Link: Database connection FAQ + +3. **General Troubleshooting Approach** + - Best practice: Always check logs first + - Tools: PM2 logs, Docker logs, application logs + - Systematic approach: 6-step debugging process + - Common errors: Module not found, permissions, ports + - Link: Troubleshooting first steps FAQ + +### Content Structure + +Each FAQ includes: +✅ Short answer (quick reference) +✅ Detailed explanation (full context) +✅ Multiple solution options +✅ Code examples and commands +✅ Prevention strategies +✅ Links to related FAQs +✅ Last updated date + +### Database Integration + +- ✅ Added to FAQ database (not standalone pages) +- ✅ Properties set: Category (Troubleshooting), Tags, Date +- ✅ FAQ index page updated with links +- ✅ Cross-references between related questions + +### Value Added + +**From conversation** → **To structured knowledge**: +- Casual Q&A → Professional FAQ entries +- Implicit knowledge → Explicit documentation +- One-time help → Reusable resource +- 5-minute conversation → Permanent team knowledge + +**Future benefit**: +- Team can self-serve on common issues +- New team members can onboard faster +- Reduces repeated questions +- Improves troubleshooting speed + +**Knowledge captured and preserved! 📚** +``` + +## Key Features Demonstrated + +### Content Extraction +- Identified distinct Q&A pairs from conversation +- Extracted commands, solutions, and best practices +- Preserved troubleshooting workflows + +### FAQ Structure +- Short answer for quick reference +- Detailed explanation for understanding +- Multiple solutions (Options 1, 2, 3) +- Code examples with comments +- Prevention strategies +- Related questions linking + +### Database Integration +- Created in FAQ database (not standalone) +- Set appropriate properties (category, tags, date) +- Updated index page with links +- Cross-referenced related questions + +### Value Transformation +- Converted informal conversation to professional docs +- Added structure, examples, and prevention tips +- Made knowledge searchable and discoverable +- Created permanent team resource + +Perfect for: FAQ creation, knowledge preservation, team documentation + diff --git a/skills/.curated/notion-knowledge-capture/examples/decision-capture.md b/skills/.curated/notion-knowledge-capture/examples/decision-capture.md new file mode 100644 index 0000000..8aeb900 --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/examples/decision-capture.md @@ -0,0 +1,126 @@ +# Example: Decision Record Capture + +**User Request**: "Document our decision to move from REST to GraphQL API" + +## Workflow + +### 1. Extract Decision from Context +From conversation, identified: +- **Decision**: Migrate customer-facing API from REST to GraphQL +- **Context**: REST endpoints becoming unwieldy (50+ endpoints) +- **Alternatives**: Keep REST, try gRPC, adopt GraphQL +- **Rationale**: Better client experience, type safety, single endpoint + +### 2. Find Decision Log +``` +Notion:notion-search +query: "architecture decisions" or "ADR" +``` + +Found: "Architecture Decision Records" database + +### 3. Fetch Schema +``` +Notion:notion-fetch +``` + +Got properties: Decision (title), Date, Status, Domain, Impact, Deciders, Stakeholders + +### 4. Create Decision Record +``` +Notion:notion-create-pages +parent: { data_source_id: "decision-log-collection-id" } +pages: [{ + properties: { + "Decision": "Migrate to GraphQL API", + "date:Date:start": "2025-10-16", + "date:Date:is_datetime": 0, + "Status": "Accepted", + "Domain": "Architecture", + "Impact": "High" + }, + content: "[Full decision record with context, rationale, alternatives...]" +}] +``` + +**Content sample**: + +```markdown +# Migrate Customer-Facing API to GraphQL + +## Context +Our REST API has grown to 50+ endpoints with inconsistent patterns. Frontend and mobile teams request new endpoints frequently, leading to: +- API bloat and maintenance burden +- Over-fetching/under-fetching data +- Slow iteration on client features +- Inconsistent error handling + +## Decision +Migrate customer-facing API from REST to GraphQL while maintaining REST for internal services. + +## Rationale +**Why GraphQL**: +- Clients fetch exactly what they need (no over/under-fetching) +- Single endpoint, self-documenting schema +- Type safety with code generation +- Better developer experience +- Industry standard for client-facing APIs + +## Options Considered + +### Option A: Keep REST (Status Quo) +**Pros**: No migration cost, team familiar +**Cons**: Doesn't solve core problems, maintenance keeps growing +**Decision**: Rejected - doesn't address root cause + +### Option B: gRPC +**Pros**: Performance, strong typing +**Cons**: Browser support issues, steeper learning curve, not designed for client-facing +**Decision**: Rejected - better for internal services + +### Option C: GraphQL +**Pros**: Solves over/under-fetching, great DX, strong ecosystem +**Cons**: Learning curve, caching complexity, migration effort +**Decision**: **Accepted** + +## Consequences + +**Positive**: +- Faster frontend/mobile development +- Reduced API maintenance burden +- Better type safety and tooling +- Single endpoint simplifies deployment + +**Negative**: +- 3-4 month migration timeline +- Team needs training +- Need to solve caching strategy +- Monitoring/debugging patterns different + +## Implementation Plan +1. GraphQL server setup (Apollo Server) +2. Schema design workshop +3. Gradual migration (start with new features) +4. Dual-run period (both REST and GraphQL) +5. Deprecate old REST endpoints + +**Timeline**: Start Q4 2025, complete Q1 2026 +**Owner**: Backend team lead + +## Success Metrics +- API response times improve 30% +- Client fetch efficiency (less data transferred) +- Reduced new endpoint requests +- Developer satisfaction scores +``` + +### 5. Make Discoverable +Added link from Architecture Wiki and notified team in Slack. + +## Key Success Factors +- Captured decision while context fresh +- Documented alternatives considered +- Included both pros and cons +- Clear implementation plan +- Saved to decision log for future reference +- Made discoverable for team diff --git a/skills/.curated/notion-knowledge-capture/examples/how-to-guide.md b/skills/.curated/notion-knowledge-capture/examples/how-to-guide.md new file mode 100644 index 0000000..b4f71c3 --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/examples/how-to-guide.md @@ -0,0 +1,118 @@ +# Example: How-To Guide from Discussion + +**User Request**: "Save our discussion about deploying to production as a how-to guide" + +## Workflow + +### 1. Extract Content from Chat +From conversation, identified: +- Deployment prerequisites +- Step-by-step procedure +- Common issues and solutions +- Best practices and tips + +### 2. Structure as How-To +Organized into: +- Overview & prerequisites +- Numbered deployment steps +- Verification steps +- Troubleshooting section +- Related resources + +### 3. Find Location +``` +Notion:notion-search +query: "deployment documentation" +``` +Found: Engineering Wiki → Deployment section + +### 4. Create Guide +``` +Notion:notion-create-pages +parent: { page_id: "deployment-section-id" } +``` + +## Output + +```markdown +# How to Deploy to Production + +## Overview +Production deployment using GitHub Actions with zero-downtime rolling updates. +**Time Required**: 15-20 minutes | **Complexity**: Intermediate + +## Prerequisites +- [ ] PR approved and merged to main +- [ ] All CI tests passing +- [ ] Database migrations reviewed +- [ ] Feature flags configured + +## Deployment Steps + +1. **Verify main branch is ready** + ```bash + git checkout main && git pull + ``` + +2. **Tag release** + ```bash + git tag -a v1.2.3 -m "Release v1.2.3" + git push origin v1.2.3 + ``` + +3. **Trigger deployment** + - GitHub Actions auto-starts from tag push + - Monitor: https://github.com/org/repo/actions + +4. **Database migrations** (if needed) + - Auto-run in GitHub Actions + - Check logs for completion + +5. **Verify deployment** + - Wait for health checks (2-3 min) + - Test key endpoints + - Check error rates in Datadog + +## Verification Checklist +- [ ] All pods healthy in k8s dashboard +- [ ] Error rate < 0.1% in last 10 min +- [ ] Response time p95 < 500ms +- [ ] Test login flow +- [ ] Check Slack #alerts channel + +## Troubleshooting + +**Health checks failing** +→ Check pod logs: `kubectl logs -f deployment/api -n production` + +**Migration errors** +→ Rollback: Revert tag, migrations auto-rollback + +**High error rate** +→ Emergency rollback: Previous tag auto-deploys via GitHub Actions + +## Best Practices +- Deploy during low-traffic hours (2-4am PST) +- Have 2 engineers available +- Monitor for 30 min post-deploy +- Update #engineering Slack with deploy notice + +## Related Docs +- Rollback Procedure +- Database Migration Guide +``` + +### 5. Make Discoverable +``` +Notion:notion-update-page +page_id: "engineering-wiki-homepage" +command: "insert_content_after" +``` +Added link in Engineering Wiki → How-To Guides section + +## Key Success Factors +- Captured tribal knowledge from discussion +- Structured as actionable steps +- Included troubleshooting from experience +- Made discoverable by linking from wiki index +- Added metadata (time, complexity) diff --git a/skills/.curated/notion-knowledge-capture/reference/database-best-practices.md b/skills/.curated/notion-knowledge-capture/reference/database-best-practices.md new file mode 100644 index 0000000..435eb7b --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/reference/database-best-practices.md @@ -0,0 +1,112 @@ +# Database Best Practices + +General guidance for creating and maintaining knowledge capture databases. + +## Core Principles + +### 1. Keep It Simple +- Start with core properties +- Add more only when needed +- Don't over-engineer + +### 2. Use Consistent Naming +- Title property for main identifier +- Status for lifecycle tracking +- Tags for flexible categorization +- Owner for accountability + +### 3. Include Metadata +- Created/Updated timestamps +- Owner or maintainer +- Last reviewed dates +- Status indicators + +### 4. Enable Discovery +- Use tags liberally +- Create helpful views +- Link related content +- Use clear titles + +### 5. Plan for Scale +- Consider filters early +- Use relations for connections +- Think about search +- Organize with categories + +## Creating a Database + +### Using `Notion:notion-create-database` + +Example for documentation database: + +```javascript +{ + "parent": {"page_id": "wiki-page-id"}, + "title": [{"text": {"content": "Team Documentation"}}], + "properties": { + "Type": { + "select": { + "options": [ + {"name": "How-To", "color": "blue"}, + {"name": "Concept", "color": "green"}, + {"name": "Reference", "color": "gray"}, + {"name": "FAQ", "color": "yellow"} + ] + } + }, + "Category": { + "select": { + "options": [ + {"name": "Engineering", "color": "red"}, + {"name": "Product", "color": "purple"}, + {"name": "Design", "color": "pink"} + ] + } + }, + "Tags": {"multi_select": {"options": []}}, + "Owner": {"people": {}}, + "Status": { + "select": { + "options": [ + {"name": "Draft", "color": "gray"}, + {"name": "Final", "color": "green"}, + {"name": "Deprecated", "color": "red"} + ] + } + } + } +} +``` + +### Fetching Database Schema + +Before creating pages, always fetch database to get schema: + +``` +Notion:notion-fetch +id: "database-url-or-id" +``` + +This returns the exact property names and types to use. + +## Database Selection Guide + +| Need | Use This Database | +|------|-------------------| +| General documentation | [Documentation Database](documentation-database.md) | +| Track decisions | [Decision Log](decision-log-database.md) | +| Q&A knowledge base | [FAQ Database](faq-database.md) | +| Team-specific content | [Team Wiki](team-wiki-database.md) | +| Step-by-step guides | [How-To Guide Database](how-to-guide-database.md) | +| Incident/project learnings | [Learning Database](learning-database.md) | + +## Tips + +1. **Start with general documentation database** - most flexible +2. **Add specialized databases** as needs emerge (FAQ, Decisions) +3. **Use relations** to connect related docs +4. **Create views** for common use cases +5. **Review properties** quarterly - remove unused ones +6. **Document the schema** in database description +7. **Train team** on property usage and conventions + diff --git a/skills/.curated/notion-knowledge-capture/reference/decision-log-database.md b/skills/.curated/notion-knowledge-capture/reference/decision-log-database.md new file mode 100644 index 0000000..2a7e6e4 --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/reference/decision-log-database.md @@ -0,0 +1,58 @@ +# Decision Log Database (ADR - Architecture Decision Records) + +**Purpose**: Track important decisions with context and rationale. + +## Schema + +| Property | Type | Options | Purpose | +|----------|------|---------|---------| +| **Decision** | title | - | What was decided | +| **Date** | date | - | When decision was made | +| **Status** | select | Proposed, Accepted, Superseded, Deprecated | Current decision status | +| **Domain** | select | Architecture, Product, Business, Design, Operations | Decision category | +| **Impact** | select | High, Medium, Low | Expected impact level | +| **Deciders** | people | - | Who made the decision | +| **Stakeholders** | people | - | Who's affected by decision | +| **Related Decisions** | relation | Links to other decisions | Context and dependencies | + +## Usage + +``` +Create decision records with properties: +{ + "Decision": "Use PostgreSQL for Primary Database", + "Date": "2025-10-15", + "Status": "Accepted", + "Domain": "Architecture", + "Impact": "High", + "Deciders": [tech_lead, architect], + "Stakeholders": [eng_team] +} +``` + +## Content Template + +Each decision page should include: +- **Context**: Why this decision was needed +- **Decision**: What was decided +- **Rationale**: Why this option was chosen +- **Options Considered**: Alternatives and trade-offs +- **Consequences**: Expected outcomes (positive and negative) +- **Implementation**: How decision will be executed + +## Views + +**Recent Decisions**: Sort by Date descending +**Active Decisions**: Filter where Status = "Accepted" +**By Domain**: Group by Domain +**High Impact**: Filter where Impact = "High" +**Pending**: Filter where Status = "Proposed" + +## Best Practices + +1. **Document immediately**: Record decisions when made, while context is fresh +2. **Include alternatives**: Show what was considered and why it wasn't chosen +3. **Track superseded decisions**: Update status when decisions change +4. **Link related decisions**: Use relations to show dependencies +5. **Review periodically**: Check if old decisions are still valid + diff --git a/skills/.curated/notion-knowledge-capture/reference/documentation-database.md b/skills/.curated/notion-knowledge-capture/reference/documentation-database.md new file mode 100644 index 0000000..ebb2833 --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/reference/documentation-database.md @@ -0,0 +1,93 @@ +# General Documentation Database + +**Purpose**: Store all types of documentation in a searchable, organized database. + +## Schema + +| Property | Type | Options | Purpose | +|----------|------|---------|---------| +| **Title** | title | - | Document name | +| **Type** | select | How-To, Concept, Reference, FAQ, Decision, Post-Mortem | Categorize content type | +| **Category** | select | Engineering, Product, Design, Operations, General | Organize by department/topic | +| **Tags** | multi_select | - | Additional categorization (languages, tools, topics) | +| **Status** | select | Draft, In Review, Final, Deprecated | Track document lifecycle | +| **Owner** | people | - | Document maintainer | +| **Created** | created_time | - | Auto-populated creation date | +| **Last Updated** | last_edited_time | - | Auto-populated last edit | +| **Last Reviewed** | date | - | Manual review tracking | + +## Usage + +``` +Create pages with properties: +{ + "Title": "How to Deploy to Production", + "Type": "How-To", + "Category": "Engineering", + "Tags": "deployment, production, DevOps", + "Status": "Final", + "Owner": [current_user], + "Last Reviewed": "2025-10-01" +} +``` + +## Views + +**By Type**: Group by Type property +**By Category**: Group by Category property +**Recent Updates**: Sort by Last Updated descending +**Needs Review**: Filter where Last Reviewed > 90 days ago +**Draft Docs**: Filter where Status = "Draft" + +## Creating This Database + +Use `Notion:notion-create-database`: + +```javascript +{ + "parent": {"page_id": "wiki-page-id"}, + "title": [{"text": {"content": "Team Documentation"}}], + "properties": { + "Type": { + "select": { + "options": [ + {"name": "How-To", "color": "blue"}, + {"name": "Concept", "color": "green"}, + {"name": "Reference", "color": "gray"}, + {"name": "FAQ", "color": "yellow"} + ] + } + }, + "Category": { + "select": { + "options": [ + {"name": "Engineering", "color": "red"}, + {"name": "Product", "color": "purple"}, + {"name": "Design", "color": "pink"} + ] + } + }, + "Tags": {"multi_select": {"options": []}}, + "Owner": {"people": {}}, + "Status": { + "select": { + "options": [ + {"name": "Draft", "color": "gray"}, + {"name": "Final", "color": "green"}, + {"name": "Deprecated", "color": "red"} + ] + } + } + } +} +``` + +## Best Practices + +1. **Start with this schema** - most flexible for general documentation +2. **Use relations** to connect related docs +3. **Create views** for common use cases +4. **Review properties** quarterly - remove unused ones +5. **Document the schema** in database description +6. **Train team** on property usage and conventions + diff --git a/skills/.curated/notion-knowledge-capture/reference/faq-database.md b/skills/.curated/notion-knowledge-capture/reference/faq-database.md new file mode 100644 index 0000000..32457dd --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/reference/faq-database.md @@ -0,0 +1,57 @@ +# FAQ Database + +**Purpose**: Organize frequently asked questions with answers. + +## Schema + +| Property | Type | Options | Purpose | +|----------|------|---------|---------| +| **Question** | title | - | The question being asked | +| **Category** | select | Product, Engineering, Support, HR, General | Question topic | +| **Tags** | multi_select | - | Specific topics (auth, billing, onboarding, etc.) | +| **Answer Type** | select | Quick Answer, Detailed Guide, Link to Docs | Response format | +| **Last Reviewed** | date | - | When answer was verified | +| **Helpful Count** | number | - | Track usefulness (optional) | +| **Audience** | select | Internal, External, All | Who should see this | +| **Related Questions** | relation | Links to related FAQs | Connect similar topics | + +## Usage + +``` +Create FAQ entries with properties: +{ + "Question": "How do I reset my password?", + "Category": "Support", + "Tags": "authentication, password, login", + "Answer Type": "Quick Answer", + "Last Reviewed": "2025-10-01", + "Audience": "External" +} +``` + +## Content Template + +Each FAQ page should include: +- **Short Answer**: 1-2 sentence quick response +- **Detailed Explanation**: Full answer with context +- **Steps** (if applicable): Numbered procedure +- **Screenshots** (if helpful): Visual guidance +- **Related Questions**: Links to similar FAQs +- **Additional Resources**: External docs or videos + +## Views + +**By Category**: Group by Category +**Recently Updated**: Sort by Last Reviewed descending +**Needs Review**: Filter where Last Reviewed > 180 days ago +**External FAQs**: Filter where Audience contains "External" +**Popular**: Sort by Helpful Count descending (if tracking) + +## Best Practices + +1. **Use clear questions**: Write questions as users would ask them +2. **Provide quick answers**: Lead with the direct answer, then elaborate +3. **Link related FAQs**: Help users discover related information +4. **Review regularly**: Keep answers current and accurate +5. **Track what's helpful**: Use feedback to improve frequently accessed FAQs + diff --git a/skills/.curated/notion-knowledge-capture/reference/how-to-guide-database.md b/skills/.curated/notion-knowledge-capture/reference/how-to-guide-database.md new file mode 100644 index 0000000..57593b1 --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/reference/how-to-guide-database.md @@ -0,0 +1,38 @@ +# How-To Guide Database + +**Purpose**: Procedural documentation for common tasks. + +## Schema + +| Property | Type | Options | Purpose | +|----------|------|---------|---------| +| **Title** | title | - | "How to [Task]" | +| **Complexity** | select | Beginner, Intermediate, Advanced | Skill level required | +| **Time Required** | number | - | Estimated minutes to complete | +| **Prerequisites** | relation | Links to other guides | Required knowledge | +| **Category** | select | Development, Deployment, Testing, Tools | Task category | +| **Last Tested** | date | - | When procedure was verified | +| **Tags** | multi_select | - | Technology/tool tags | + +## Usage + +``` +Create how-to guides with properties: +{ + "Title": "How to Set Up Local Development Environment", + "Complexity": "Beginner", + "Time Required": 30, + "Category": "Development", + "Last Tested": "2025-10-01", + "Tags": "setup, environment, docker" +} +``` + +## Best Practices + +1. **Use consistent naming**: Always start with "How to..." +2. **Test procedures**: Verify steps work before publishing +3. **Include time estimates**: Help users plan their time +4. **Link prerequisites**: Make dependencies clear +5. **Update regularly**: Re-test procedures when tools/systems change + diff --git a/skills/.curated/notion-knowledge-capture/reference/learning-database.md b/skills/.curated/notion-knowledge-capture/reference/learning-database.md new file mode 100644 index 0000000..02f5f35 --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/reference/learning-database.md @@ -0,0 +1,35 @@ +# Learning/Post-Mortem Database + +**Purpose**: Capture learnings from incidents, projects, or experiences. + +## Schema + +| Property | Type | Options | Purpose | +|----------|------|---------|---------| +| **Title** | title | - | Event or project name | +| **Date** | date | - | When it happened | +| **Type** | select | Incident, Project, Experiment, Retrospective | Learning type | +| **Severity** | select | Critical, Major, Minor | Impact level (for incidents) | +| **Team** | people | - | Who was involved | +| **Key Learnings** | number | - | Count of learnings | +| **Action Items** | relation | Links to tasks | Follow-up actions | + +## Content Template + +Each learning page should include: +- **What Happened**: Situation description +- **What Went Well**: Success factors +- **What Didn't Go Well**: Problems encountered +- **Root Causes**: Why things happened +- **Learnings**: Key takeaways +- **Action Items**: Improvements to implement + +## Best Practices + +1. **Blameless approach**: Focus on systems and processes, not individuals +2. **Document quickly**: Capture while memory is fresh +3. **Identify root causes**: Go beyond surface-level problems +4. **Create action items**: Turn learnings into improvements +5. **Follow up**: Track that action items are completed +6. **Share widely**: Make learnings accessible to entire team + diff --git a/skills/.curated/notion-knowledge-capture/reference/team-wiki-database.md b/skills/.curated/notion-knowledge-capture/reference/team-wiki-database.md new file mode 100644 index 0000000..e7b741f --- /dev/null +++ b/skills/.curated/notion-knowledge-capture/reference/team-wiki-database.md @@ -0,0 +1,27 @@ +# Team Wiki Database + +**Purpose**: Centralized team knowledge and resources. + +## Schema + +| Property | Type | Options | Purpose | +|----------|------|---------|---------| +| **Title** | title | - | Page name | +| **Section** | select | Getting Started, Processes, Tools, Reference, Onboarding | Wiki organization | +| **Tags** | multi_select | - | Topic tags | +| **Owner** | people | - | Page maintainer | +| **Last Updated** | last_edited_time | - | Auto-tracked | +| **Visibility** | select | Public, Team Only, Confidential | Access level | + +## Usage + +Use for team-specific documentation that doesn't fit other databases. + +## Best Practices + +1. **Organize by sections**: Use clear top-level organization +2. **Assign owners**: Every page should have a maintainer +3. **Control visibility**: Set appropriate access levels +4. **Link extensively**: Connect related pages +5. **Keep current**: Regular reviews to remove outdated content + diff --git a/skills/.curated/notion-meeting-intelligence/LICENSE.txt b/skills/.curated/notion-meeting-intelligence/LICENSE.txt new file mode 100644 index 0000000..0871708 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/LICENSE.txt @@ -0,0 +1,7 @@ +Copyright 2025 Notion Labs, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/skills/.curated/notion-meeting-intelligence/SKILL.md b/skills/.curated/notion-meeting-intelligence/SKILL.md new file mode 100644 index 0000000..27e5ac2 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/SKILL.md @@ -0,0 +1,13 @@ +--- +name: notion-meeting-intelligence +description: Prepare meeting materials with Notion context and Codex research; use when prepping meetings, creating agendas, or gathering meeting context. +--- + +# Meeting Intelligence + +- Search Notion for related pages using `Notion:notion-search` +- Fetch details with `Notion:notion-fetch` +- Enrich with Codex research (industry insights, best practices) +- Create internal pre-read for attendees +- Create external agenda for all participants +- See reference/template-selection-guide.md for meeting templates diff --git a/skills/.curated/notion-meeting-intelligence/evaluations/README.md b/skills/.curated/notion-meeting-intelligence/evaluations/README.md new file mode 100644 index 0000000..eb77e17 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/evaluations/README.md @@ -0,0 +1,101 @@ +# Meeting Intelligence Skill Evaluations + +Evaluation scenarios for testing the Meeting Intelligence skill across different Codex models. + +## Purpose + +These evaluations ensure the Meeting Intelligence skill: +- Gathers context from Notion workspace +- Enriches with Codex research appropriately +- Creates both internal pre-reads and external agendas +- Distinguishes between Notion facts and Codex insights +- Works consistently across Haiku, Sonnet, and Opus + +## Evaluation Files + +### decision-meeting-prep.json +Tests preparation for a decision-making meeting. + +**Scenario**: Prep for database migration decision meeting +**Key Behaviors**: +- Searches Notion for migration context (specs, discussions, options) +- Fetches 2-3 relevant pages +- Enriches with Codex research (decision frameworks, migration best practices) +- Creates comprehensive internal pre-read with recommendation +- Creates clean, professional external agenda +- Clearly distinguishes Notion facts from Codex insights +- Cross-links both documents + +### status-meeting-prep.json +Tests preparation for a status update or review meeting. + +**Scenario**: Prep for project status review +**Key Behaviors**: +- Gathers project metrics and progress from Notion +- Fetches relevant pages (roadmap, tasks, milestones) +- Adds Codex context (industry benchmarks, best practices) +- Creates internal pre-read with honest assessment +- Creates external agenda with structured flow +- Includes source citations using mention-page tags +- Time-boxes agenda items + +## Running Evaluations + +1. Enable the `meeting-intelligence` skill +2. Submit the query from the evaluation file +3. Verify the skill searches Notion first (not Codex research) +4. Check that TWO documents are created (internal + external) +5. Verify Codex enrichment adds value without replacing Notion content +6. Test with Haiku, Sonnet, and Opus + +## Expected Skill Behaviors + +Meeting Intelligence evaluations should verify: + +### Notion Context Gathering +- Searches workspace for relevant context first +- Fetches specific pages (not generic) +- Extracts key information from Notion content +- Cites sources using mention-page tags + +### Codex Research Integration +- Adds industry context, frameworks, or best practices +- Enrichment is relevant and valuable (not filler) +- Clearly distinguishes Notion facts from Codex insights +- Research complements (doesn't replace) Notion content + +### Two-Document Creation +- **Internal Pre-Read**: Comprehensive, includes strategy, recommendations, detailed pros/cons +- **External Agenda**: Professional, focused on meeting flow, no internal strategy +- Both documents are clearly labeled +- Documents are cross-linked + +### Document Quality +- Pre-read follows structure: Overview → Background → Current Status → Context & Insights → Discussion Points +- Agenda follows structure: Details → Objective → Agenda Items (with times) → Decisions → Actions → Resources +- Titles include date or meeting context +- Content is actionable and meeting-ready + +## Creating New Evaluations + +When adding Meeting Intelligence evaluations: + +1. **Test different meeting types** - Decision, status, brainstorm, 1:1, sprint planning, retrospective +2. **Vary complexity** - Simple updates vs. complex strategic decisions +3. **Test with/without Notion content** - Rich workspace vs. minimal existing pages +4. **Verify enrichment value** - Is Codex research genuinely helpful? +5. **Check internal/external distinction** - Is sensitive info kept in pre-read only? + +## Example Success Criteria + +**Good** (specific, testable): +- "Creates TWO documents (internal pre-read + external agenda)" +- "Internal pre-read marked 'INTERNAL ONLY' or 'For team only'" +- "Cites at least 2-3 Notion pages using mention-page tags" +- "Agenda includes time allocations for each section" +- "Codex enrichment includes decision frameworks or best practices" + +**Bad** (vague, untestable): +- "Creates meeting materials" +- "Gathers context effectively" +- "Prepares well" diff --git a/skills/.curated/notion-meeting-intelligence/evaluations/decision-meeting-prep.json b/skills/.curated/notion-meeting-intelligence/evaluations/decision-meeting-prep.json new file mode 100644 index 0000000..3eca6b5 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/evaluations/decision-meeting-prep.json @@ -0,0 +1,35 @@ +{ + "name": "Decision Meeting Preparation", + "skills": ["meeting-intelligence"], + "query": "Prep for tomorrow's meeting where we need to decide on our database migration approach. Create both an internal pre-read for the team and an agenda for the meeting.", + "expected_behavior": [ + "Step 1: Uses Notion:notion-search to find context about database migration (project pages, technical specs, previous discussions, options analysis)", + "Step 2: Fetches at least 2-3 relevant pages using Notion:notion-fetch to gather information from Notion", + "Step 3: Identifies the decision to be made and available options from fetched Notion content", + "Step 4: Enriches with Codex research - adds decision-making frameworks (e.g., cost-benefit analysis, risk assessment), technical context for migration approaches, best practices for database migrations", + "Step 5: Distinguishes Notion facts from Codex insights in synthesis", + "Step 6: Creates INTERNAL PRE-READ using Notion:notion-create-pages with title like 'INTERNAL: Database Migration Decision - Pre-Read - [Date]'", + "Step 6a: Internal pre-read includes: Meeting overview, background context (from Notion), current status and technical details, context & insights (from Codex research on migration best practices), decision options with detailed pros/cons, recommendation with rationale, what we need from meeting", + "Step 6b: Internal pre-read marked clearly as 'INTERNAL ONLY' or 'For team only'", + "Step 7: Creates EXTERNAL AGENDA using Notion:notion-create-pages with title like 'Meeting Agenda: Database Migration Decision - [Date]'", + "Step 7a: External agenda includes: Meeting details, objective (clear decision to make), agenda items with time allocations, discussion topics, decisions needed, action items section (empty), related resources with link to pre-read", + "Step 7b: External agenda is clean, professional, focused (no internal strategy or detailed pros/cons)", + "Step 8: Links both documents together (agenda mentions pre-read, pre-read mentions agenda)", + "Both documents link to source pages using " + ], + "success_criteria": [ + "TWO documents are created (internal pre-read + external agenda), not just one", + "Internal pre-read is comprehensive with: Notion context + Codex insights + detailed pros/cons + recommendation", + "Internal pre-read is clearly marked 'INTERNAL' or 'For team only'", + "External agenda is professional, structured, focused on meeting flow (not internal strategy)", + "Codex enrichment is present and adds value (decision frameworks, migration best practices, risk patterns)", + "Notion facts are clearly sourced, Codex insights are distinguished", + "At least 2-3 Notion source pages are cited using mention-page tags", + "Internal pre-read follows structure from SKILL.md Step 5 (Meeting Overview → Background → Current Status → Context & Insights → Key Discussion Points → What We Need)", + "External agenda follows structure from SKILL.md Step 6 (Meeting Details → Objective → Agenda Items → Discussion Topics → Decisions Needed → Action Items → Related Resources)", + "Documents are cross-linked (pre-read mentions agenda, agenda mentions pre-read)", + "Meeting date is included in both titles", + "Uses correct tool names (Notion:notion-search, Notion:notion-fetch, Notion:notion-create-pages for BOTH documents)" + ] +} + diff --git a/skills/.curated/notion-meeting-intelligence/evaluations/status-meeting-prep.json b/skills/.curated/notion-meeting-intelligence/evaluations/status-meeting-prep.json new file mode 100644 index 0000000..1498787 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/evaluations/status-meeting-prep.json @@ -0,0 +1,35 @@ +{ + "name": "Status Update Meeting Preparation", + "skills": ["meeting-intelligence", "task-manager"], + "query": "Prep for Friday's project status meeting on the Mobile App Redesign project. Create both an internal pre-read and an external agenda.", + "expected_behavior": [ + "Step 1: Uses Notion:notion-search to find Mobile App Redesign project page", + "Step 2: Fetches project page using Notion:notion-fetch to get current status and context", + "Step 3: Uses Notion:notion-search to find tasks database", + "Step 4: Queries task database using Notion:notion-query-data-sources for project tasks (WHERE Project = 'Mobile App Redesign')", + "Step 5: Analyzes task data: calculates completion %, identifies completed work, in-progress items, and blockers", + "Step 6: Enriches with Codex research - adds project management insights (velocity trends, risk patterns, common project pitfalls), suggests discussion frameworks if risks identified, provides context on timeline implications", + "Step 7: Creates INTERNAL PRE-READ using Notion:notion-create-pages with title 'INTERNAL: Mobile App Redesign Status - Pre-Read - [Date]'", + "Step 7a: Internal pre-read includes: Project overview, current status with metrics (from Notion/tasks), progress summary with specifics, context & insights (Codex research on project health patterns), honest assessment of challenges/risks, what we need from meeting", + "Step 7b: Internal pre-read contains detailed metrics, blockers, and strategic considerations", + "Step 8: Creates EXTERNAL AGENDA using Notion:notion-create-pages with title 'Meeting Agenda: Mobile App Redesign Status Update - [Date]'", + "Step 8a: External agenda uses Status Update structure: Meeting Details → Objective → Agenda Items (timed) → Discussion Topics → Action Items", + "Step 8b: External agenda is concise, professional, focuses on meeting flow (summary-level metrics only)", + "Step 9: Links both documents together", + "Both documents link to project page and task database using and " + ], + "success_criteria": [ + "TWO documents are created (internal pre-read + external agenda)", + "Internal pre-read contains: Detailed metrics from task query, honest assessment of blockers/risks, Codex insights on project health patterns, strategic considerations", + "Internal pre-read is marked 'INTERNAL' or 'For team only'", + "External agenda is professional status update format with: Overall status, progress summary (high-level), upcoming work, discussion topics, action items section", + "External agenda does NOT contain detailed risk analysis or internal strategic discussion (that's in pre-read)", + "Progress metrics are accurate based on Notion:notion-query-data-sources results (e.g., X complete, Y in progress, Z blocked)", + "Blockers identified from task query are included in internal pre-read with full context", + "Codex enrichment adds value (project management insights, risk patterns, velocity analysis)", + "Links to project page and task database using mention tags", + "Documents are cross-linked for easy navigation", + "Uses correct tool names (Notion:notion-search, Notion:notion-fetch, Notion:notion-query-data-sources, Notion:notion-create-pages for BOTH documents)" + ] +} + diff --git a/skills/.curated/notion-meeting-intelligence/examples/customer-meeting.md b/skills/.curated/notion-meeting-intelligence/examples/customer-meeting.md new file mode 100644 index 0000000..a975e11 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/examples/customer-meeting.md @@ -0,0 +1,125 @@ +# Example: Customer Meeting Prep + +**User Request**: "Prep for sales meeting with Acme Corp on Thursday" + +## Workflow + +### 1. Search Customer Info +``` +Notion:notion-search +query: "Acme Corp" +``` + +Found: +- CRM notes from initial call +- Product demo feedback +- Pricing proposal +- Competitor analysis + +### 2. Fetch Details +``` +Notion:notion-fetch (4 pages) +``` + +**Key context**: +- **Company**: 500-person fintech startup, Series B +- **Pain Points**: Manual workflows, data silos, scaling issues +- **Decision Makers**: CTO (technical), VP Product (user needs), CFO (budget) +- **Timeline**: Need solution by Q1 +- **Budget**: $50-75K/year range +- **Competition**: Evaluating us vs. Competitor A and Competitor B + +### 3. Add Research Context +Codex research added: +- Fintech industry compliance requirements +- Common integration needs for financial products +- Typical procurement processes for Series B companies + +### 4. Create Internal Pre-Read +``` +Notion:notion-create-pages +pages: [{ + properties: { + title: "Acme Corp Meeting - Pre-Read (Internal)" + }, + content: "# Acme Corp Meeting - Pre-Read (Internal) + +## Company Overview +**Company**: Acme Corp (500-person fintech, Series B) +**Decision Makers**: CTO, VP Product, CFO +Source: CRM Notes + +## Their Pain Points → Our Solutions +- Manual workflows → Workflow automation +- Data silos → API integrations +- Scaling issues → Enterprise features + +## Competitive Position +**Our advantages over Competitor A/B**: +- Better integration ecosystem (Stripe, Plaid) +- Stronger compliance features +- Faster implementation (4 weeks vs 12 weeks) + +## Pricing Strategy +Recommend: $60K/year (mid-range of their budget) + +## Potential Objections & Responses +..." +}] +``` + +### 5. Create Meeting Agenda +``` +Notion:notion-create-pages +pages: [{ + properties: { + title: "Acme Corp - Product Demo & Q&A" + }, + content: "# Acme Corp - Product Demo & Q&A + +## Meeting Details +**Date**: Thursday, Oct 17, 2025 @ 2pm PST +**Attendees**: CTO, VP Product, CFO (Acme) | Sales Lead, Solutions Engineer (Us) +**Duration**: 60 minutes + +## Objective +Demonstrate how our platform solves Acme's workflow automation and integration challenges. + +## Agenda + +**1. Introductions** (5 min) + +**2. Understand Current Workflow** (10 min) +- Current pain points +- Integration requirements +- Success criteria + +**3. Product Demo** (25 min) +- Workflow automation capabilities +- API integrations (Stripe, Plaid) +- Security & compliance features + +**4. Pricing & Implementation** (10 min) + +**5. Next Steps** (10 min) +" +}] +``` + +### 6. Link Resources +Connected agenda to CRM page, pricing sheet, and technical integration docs. + +## Outputs + +**Internal Pre-Read**: Full context for sales team +**Customer Agenda**: Professional meeting structure +**Both in Notion** with links to supporting materials + +## Key Success Factors +- Understood customer's specific pain points +- Researched industry context (fintech compliance) +- Mapped features to their needs +- Prepared competitive differentiators +- Structured demo around their use cases +- Pre-planned objection responses +- Clear next steps in agenda diff --git a/skills/.curated/notion-meeting-intelligence/examples/executive-review.md b/skills/.curated/notion-meeting-intelligence/examples/executive-review.md new file mode 100644 index 0000000..99a1331 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/examples/executive-review.md @@ -0,0 +1,78 @@ +# Example: Executive Review Prep + +**User Request**: "Prep for quarterly executive review on Friday" + +## Workflow + +### 1. Search for Context +``` +Notion:notion-search +query: "Q4 objectives" + "KPIs" + "quarterly results" +``` + +Found: +- Q4 OKRs and progress +- Product metrics dashboard +- Engineering velocity reports +- Customer feedback summary + +### 2. Fetch & Analyze +``` +Notion:notion-fetch (5 pages) +``` + +**Key metrics**: +- **Revenue**: $2.4M ARR (96% of Q4 target) +- **Customer Growth**: 145 new customers (exceeds 120 target) +- **Churn**: 3.2% (below 5% target) +- **Product**: 3 major features shipped, 2 in beta +- **Engineering**: 94% uptime (above 95% SLA) + +### 3. Add Codex Research Context +Added context on: +- Industry benchmarks for SaaS metrics +- Typical Q4 sales patterns +- Best practices for executive presentations + +### 4. Create Pre-Read (Internal) +``` +Notion:notion-create-pages +title: "Q4 Review - Pre-Read (Internal)" +``` + +**Pre-read sections**: +- **Executive Summary**: Strong quarter, missed revenue by 4% but exceeded customer growth +- **Detailed Metrics**: All KPIs with trend lines +- **Wins**: Product launches, key customer acquisitions +- **Challenges**: Sales pipeline conversion, engineering hiring +- **Q1 Preview**: Strategic priorities + +### 5. Create Presentation Agenda +``` +Notion:notion-create-pages +title: "Q4 Executive Review - Agenda" +``` + +**Agenda** (90 min): +- Q4 Results Overview (15 min) +- Revenue & Growth Deep Dive (20 min) +- Product & Engineering Update (20 min) +- Customer Success Highlights (15 min) +- Q1 Strategic Plan (15 min) +- Discussion & Questions (15 min) + +### 6. Link Supporting Docs +Connected to OKRs, metrics dashboards, and Q1 planning docs. + +## Outputs + +**Internal Pre-Read**: Comprehensive context with honest assessment +**Executive Agenda**: Structured 90-min presentation +**Both in Notion** with links to supporting data + +## Key Success Factors +- Synthesized data from multiple sources (OKRs, metrics, feedback) +- Added industry context and benchmarks +- Created honest internal assessment (not just wins) +- Structured agenda with time allocations +- Linked to source data for drill-down during Q&A diff --git a/skills/.curated/notion-meeting-intelligence/examples/project-decision.md b/skills/.curated/notion-meeting-intelligence/examples/project-decision.md new file mode 100644 index 0000000..d4a8859 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/examples/project-decision.md @@ -0,0 +1,431 @@ +# Example: Project Decision Meeting Prep + +## User Request + +> "Prep for tomorrow's architecture meeting where we need to decide on database migration strategy" + +## Workflow Execution + +### Step 1: Search for Context + +``` +Notion:notion-search +query: "database migration" +query_type: "internal" +teamspace_id: "engineering-teamspace-id" +filters: { + created_date_range: { + start_date: "2024-01-01" + } +} +``` + +**Results Found:** +- "Database Migration Proposal" (Engineering) +- "Current Database Performance Issues" (Engineering) +- "Migration Options Analysis" (Architecture) +- "Previous Migration Post-mortem" (Engineering) + +### Step 2: Fetch Relevant Pages + +``` +Notion:notion-fetch +id: "database-migration-proposal-page-id" +``` + +**Extracted**: Proposes migrating from MongoDB to PostgreSQL, outlines timeline and risks + +``` +Notion:notion-fetch +id: "database-performance-issues-page-id" +``` + +**Extracted**: Current pain points - slow queries, schema flexibility issues, transaction limitations + +``` +Notion:notion-fetch +id: "migration-options-analysis-page-id" +``` + +**Extracted**: Three options analyzed: +1. Stay on MongoDB with optimizations +2. Migrate to PostgreSQL +3. Hybrid approach (MongoDB + PostgreSQL) + +``` +Notion:notion-fetch +id: "previous-migration-postmortem-page-id" +``` + +**Extracted**: Lessons from 2023 Redis migration - importance of rollback plan, testing strategy + +### Step 3: Synthesize Pre-Read + +**Key Information Identified:** +- **Problem**: MongoDB performance degrading, schema flexibility causing data consistency issues +- **Options**: Three approaches with different trade-offs +- **Recommendation**: PostgreSQL migration favored by engineering team +- **Concerns**: Downtime requirements, data migration complexity, application changes needed +- **Historical context**: Previous migration took 6 weeks, had rollback issues + +### Step 4: Create Meeting Agenda + +``` +Notion:notion-create-pages + +parent: { page_id: "meetings-parent-id" } + +pages: [{ + properties: { + "title": "Architecture Decision: Database Migration Strategy - Oct 15, 2025" + }, + content: "[Decision meeting agenda]" +}] +``` + +**Agenda Created:** + +```markdown +# Architecture Decision: Database Migration Strategy + +## Meeting Details +**Date & Time**: October 15, 2025 at 2:00 PM +**Duration**: 90 minutes +**Location**: Conference Room B / Zoom +**Facilitator**: Sarah Chen (Engineering Lead) +**Attendees**: +- Sarah Chen (Engineering Lead) +- David Kim (CTO) +- Alice Wang (Backend Team Lead) +- Bob Martinez (DevOps Lead) +- Carol Johnson (Product Director) + +## Pre-Read Summary + +### Background + +Our MongoDB database is experiencing performance degradation as we scale. Query response times have increased from 50ms to 400ms average over the past 6 months. The schema-less nature that initially provided flexibility is now causing data consistency issues and making application logic more complex. + +**Source**: Current Database Performance Issues + +### Current Situation + +**Performance metrics**: +- Average query time: 400ms (was 50ms 6 months ago) +- p95 query time: 1.2s (was 200ms) +- Database size: 500GB (growing 20GB/month) +- Connection pool exhaustion during peak traffic + +**Technical debt**: +- 15+ application-layer validation rules compensating for lack of schema +- Complex data migration scripts for schema changes +- Limited transaction support causing race conditions + +**Source**: Database Migration Proposal + +### Historical Context + +We successfully migrated from Redis to Memcached in 2023, which took 6 weeks. Key learnings: +- Underestimated application code changes (3 weeks instead of 1 week) +- Rollback plan was crucial when we discovered compatibility issues +- Parallel running period (dual writes) was essential for safe migration + +**Source**: Previous Migration Post-mortem + +## Decision Required + +**Question**: Which database migration strategy should we adopt? + +**Timeline**: Need decision by end of week to include in Q4 planning + +**Impact**: +- Engineering team (4-8 weeks of work) +- Application architecture +- Operations & monitoring +- Future feature development velocity + +## Options Analysis + +### Option A: Stay on MongoDB with Optimizations + +**Description**: Invest in MongoDB performance tuning, add indexes, upgrade to latest version, implement better query patterns. + +**Pros**: +- ✅ No migration complexity +- ✅ Team familiar with MongoDB +- ✅ Can implement immediately +- ✅ Lower risk +- ✅ Estimated 2 weeks effort + +**Cons**: +- ❌ Doesn't solve fundamental schema flexibility issues +- ❌ Still limited transaction support +- ❌ Performance improvements may be temporary +- ❌ Continues technical debt accumulation + +**Cost/Effort**: 2 weeks engineering + $5K/year additional MongoDB infrastructure + +**Risk**: Medium - Improvements may not be sufficient + +**Source**: Migration Options Analysis + +### Option B: Migrate to PostgreSQL + +**Description**: Full migration from MongoDB to PostgreSQL. Redesign schema with proper constraints, implement dual-write period, then cut over. + +**Pros**: +- ✅ Solves schema consistency issues +- ✅ Full ACID transactions +- ✅ Better performance for relational queries +- ✅ Lower long-term complexity +- ✅ Industry standard, easier hiring + +**Cons**: +- ❌ High migration effort (6-8 weeks) +- ❌ Requires schema redesign +- ❌ Application code changes extensive +- ❌ Risk of data loss during migration +- ❌ Downtime required (4-6 hours estimated) + +**Cost/Effort**: 8 weeks engineering + $8K migration costs - $15K/year MongoDB savings = net $7K/year savings + +**Risk**: High - Complex migration, application changes required + +**Recommendation**: ✅ **Favored by engineering team** + +**Source**: Database Migration Proposal + +### Option C: Hybrid Approach + +**Description**: Keep MongoDB for document-heavy data (logs, analytics), migrate transactional data to PostgreSQL. Run both databases. + +**Pros**: +- ✅ Phased migration (lower risk) +- ✅ Use best tool for each data type +- ✅ Can migrate incrementally +- ✅ Smaller initial scope (4 weeks) + +**Cons**: +- ❌ Increased operational complexity +- ❌ Two databases to maintain +- ❌ Data consistency between databases challenging +- ❌ Higher infrastructure costs +- ❌ Complex application logic + +**Cost/Effort**: 4 weeks initial + ongoing complexity + $10K/year additional infrastructure + +**Risk**: Medium - Operational complexity increases + +**Source**: Migration Options Analysis + +### Option D: Do Nothing + +**Description**: Accept current performance and continue with MongoDB as-is. + +**Implications**: +- Performance continues to degrade +- Technical debt increases +- Feature development slows +- Customer experience suffers +- Eventually forced into emergency migration + +**Not recommended** + +## Discussion Topics + +### Technical Feasibility +1. Can we achieve < 4 hours downtime for Option B? +2. What's the rollback plan if PostgreSQL migration fails? +3. How do we handle data migration for 500GB? +4. Schema design - what constraints do we need? + +### Business Impact +5. What's the customer impact of 4-6 hours downtime? +6. Can we schedule migration during low-traffic period? +7. How does this affect Q4 feature roadmap? +8. Cost-benefit analysis over 2-year horizon? + +### Risk Management +9. What are the biggest risks with Option B? +10. How do we test thoroughly before cutover? +11. What's the rollback procedure and time? +12. Do we have necessary expertise on team? + +### Timeline & Resources +13. Can we allocate 2 engineers full-time for 8 weeks? +14. Do we need external consultants? +15. What's the impact on other Q4 projects? +16. When could we realistically complete this? + +## Decision Framework + +**Evaluation criteria**: +1. **Performance improvement**: Will this solve our performance issues? +2. **Technical debt**: Does this reduce or increase complexity? +3. **Risk**: What's the probability and impact of failure? +4. **Cost**: Total cost of ownership (effort + infrastructure) +5. **Timeline**: Can we complete in Q4? +6. **Reversibility**: Can we roll back if needed? + +**Decision makers**: +- Primary: David Kim (CTO) +- Consulted: Sarah Chen (Engineering), Bob Martinez (DevOps) +- Informed: Product, Executive team + +## Decision + +*[To be filled during meeting]* + +**Selected Option**: ___________________ + +**Rationale**: + +**Timeline**: + +**Owner**: ___________________ + +**Success Criteria**: + +## Action Items + +*[To be filled during meeting]* + +- [ ] [Action item] - @[Owner] - Due: [Date] +- [ ] [Action item] - @[Owner] - Due: [Date] + +## Next Steps + +**Immediate**: +- Document decision rationale +- Create detailed implementation plan +- Schedule kickoff meeting + +**Follow-up meeting**: [Date] to review migration plan + +## Related Resources + +### Primary Sources +- Database Migration Proposal +- Current Database Performance Issues +- Migration Options Analysis +- Previous Migration Post-mortem + +### Supporting Documents +- MongoDB performance metrics dashboard +- PostgreSQL evaluation results +- Cost analysis spreadsheet +``` + +### Step 5: Share Agenda + +``` +Notion:notion-create-comment +parent: { page_id: "agenda-page-id" } +rich_text: [{ + type: "text", + text: { content: "📋 Meeting agenda ready! Please review the pre-read before tomorrow's meeting. cc: @Sarah @David @Alice @Bob @Carol" } +}] +``` + +## Summary Provided to User + +```markdown +## Meeting Prep Complete ✅ + +### Meeting Details +- **Topic**: Database Migration Strategy Decision +- **Date**: October 15, 2025 at 2:00 PM +- **Duration**: 90 minutes +- **Attendees**: 5 (Engineering leads + CTO + Product) + +### Agenda Created +Architecture Decision: Database Migration Strategy + +### Pre-Read Summary + +**Problem**: MongoDB performance degrading (50ms → 400ms queries), schema flexibility causing issues + +**Decision needed**: Choose between: +1. Stay on MongoDB (optimizations) - 2 weeks, low risk +2. Migrate to PostgreSQL - 8 weeks, high value, high risk ✅ Recommended +3. Hybrid approach - 4 weeks, medium complexity +4. Do nothing - Not recommended + +**Recommendation**: Engineering team favors PostgreSQL migration + +### Key Information Included + +✅ **Background context** from 4 relevant pages +✅ **Options analysis** with pros/cons for each +✅ **Cost-benefit** breakdown +✅ **Risk assessment** for each option +✅ **Discussion topics** (16 questions organized by theme) +✅ **Decision framework** with evaluation criteria +✅ **Historical context** from previous migration +✅ **Empty sections** for decision and action items + +### Discussion Topics Prepared + +**Technical** (4 questions): +- Downtime achievability +- Rollback planning +- Data migration approach +- Schema design + +**Business** (4 questions): +- Customer impact +- Scheduling +- Roadmap impact +- Cost analysis + +**Risk** (4 questions): +- Risk identification +- Testing strategy +- Rollback procedure +- Expertise availability + +**Resources** (4 questions): +- Team allocation +- External help needs +- Project trade-offs +- Timeline realism + +### Success Factors + +1. **Comprehensive research**: 4 relevant pages analyzed +2. **Clear options**: Pros/cons for each approach +3. **Structured discussion**: 16 questions organized by theme +4. **Decision framework**: Clear criteria for evaluation +5. **Historical context**: Lessons from previous migration +6. **Ready for outcomes**: Sections prepared for decision and actions + +**Meeting is well-prepared for productive decision-making! 📊** +``` + +## Key Features Demonstrated + +### Context Gathering +- **Targeted search**: Engineering teamspace, recent documents +- **Multiple perspectives**: Performance data, proposals, analysis, historical lessons +- **Comprehensive synthesis**: Combined technical, business, and historical context + +### Options Analysis +- **Structured comparison**: Pros/cons for each option +- **Cost-benefit**: Effort and infrastructure costs included +- **Risk assessment**: Probability and impact noted +- **Recommendation**: Clear engineering preference stated + +### Decision Support +- **Discussion topics**: 16 questions organized by theme +- **Decision framework**: Evaluation criteria defined +- **Decision makers**: Roles and responsibilities clear +- **Outcome capture**: Sections ready for decision and actions + +### Meeting Structure +- **Pre-read**: Comprehensive background (can be read in 10 minutes) +- **Options**: Clear comparison for quick decision +- **Discussion**: Structured topics prevent rambling +- **Capture**: Templates for decision and actions + +Perfect for: Architecture decisions, technical trade-offs, strategic choices + diff --git a/skills/.curated/notion-meeting-intelligence/examples/sprint-planning.md b/skills/.curated/notion-meeting-intelligence/examples/sprint-planning.md new file mode 100644 index 0000000..93fbb6c --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/examples/sprint-planning.md @@ -0,0 +1,80 @@ +# Example: Sprint Planning Meeting Prep + +**User Request**: "Prepare for tomorrow's sprint planning meeting" + +## Workflow + +### 1. Search for Context +``` +Notion:notion-search +query: "sprint planning" + "product backlog" +teamspace_id: "engineering-team" +``` + +Found: +- Last sprint retrospective +- Product backlog (prioritized) +- Current sprint progress +- Team capacity notes + +### 2. Fetch Details +``` +Notion:notion-fetch (4 pages) +``` + +**Key context**: +- **Last Sprint**: Completed 32/35 story points (91%) +- **Velocity**: Consistent 30-35 points over last 3 sprints +- **Team**: 5 engineers, 1 on vacation next sprint (80% capacity) +- **Top Backlog Items**: User auth improvements, API performance, mobile responsive fixes + +### 3. Query Current Sprint Tasks +``` +Notion:notion-query-data-sources +query: "SELECT * FROM tasks WHERE Sprint = 'Sprint 24' AND Status != 'Done'" +``` + +3 tasks carrying over (technical debt items) + +### 4. Create Pre-Read (Internal) +``` +Notion:notion-create-pages +title: "Sprint 25 Planning - Pre-Read (Internal)" +``` + +**Pre-read included**: +- Sprint 24 summary (velocity, what carried over) +- Team capacity for Sprint 25 +- Top backlog candidates with story points +- Technical dependencies +- Risk items (auth changes need QA time) + +### 5. Create Agenda +``` +Notion:notion-create-pages +title: "Sprint 25 Planning - Agenda" +``` + +**Agenda**: +- Review Sprint 24 completion (5 min) +- Discuss carryover items (5 min) +- Review capacity (28 points available) +- Select backlog items (30 min) +- Identify dependencies & risks (10 min) +- Confirm commitments (10 min) + +### 6. Link Documents +Cross-linked pre-read and agenda, referenced last retro and backlog. + +## Output Summary + +**Internal Pre-Read**: Team context, capacity, blockers +**External Agenda**: Meeting structure, discussion topics +**Both saved to Notion** and linked to project pages + +## Key Success Factors +- Gathered sprint history for velocity trends +- Calculated realistic capacity (account for PTO) +- Identified carryover items upfront +- Pre-read gave team context before meeting +- Agenda kept meeting focused and timeboxed diff --git a/skills/.curated/notion-meeting-intelligence/reference/brainstorming-template.md b/skills/.curated/notion-meeting-intelligence/reference/brainstorming-template.md new file mode 100644 index 0000000..0e31334 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/reference/brainstorming-template.md @@ -0,0 +1,81 @@ +# Brainstorming Meeting Template + +Use this template for creative ideation and brainstorming sessions. + +```markdown +# [Topic] Brainstorming - [Date] + +## Meeting Details +**Date**: [Date] +**Facilitator**: [Name] +**Note-taker**: [Name] +**Attendees**: [List] + +## Objective + +[Clear statement of what we're brainstorming] + +**Success looks like**: [How we'll know brainstorming was successful] + +## Background & Context + +[Context from research - 2-3 paragraphs] + +**Related Pages**: +- Context Page 1 +- Context Page 2 + +## Constraints + +- [Constraint] +- [Constraint] +- [Constraint] + +## Seed Ideas + +[Starting ideas from research to spark discussion]: + +1. **[Idea]**: [Brief description] +2. **[Idea]**: [Brief description] + +## Ground Rules + +- No criticism during ideation +- Build on others' ideas +- Quantity over quality initially +- Wild ideas welcome + +## Brainstorming Notes + +### Ideas Generated + +[To be filled during meeting] + +1. [Idea with brief description] +2. [Idea with brief description] + +### Themes/Patterns + +[Groupings that emerge] + +## Evaluation + +[If time permits, evaluate top ideas] + +### Top Ideas + +| Idea | Feasibility | Impact | Effort | Score | +|------|-------------|---------|--------|-------| +| [Idea] | [H/M/L] | [H/M/L] | [H/M/L] | [#] | + +## Next Steps + +- [ ] [Action to explore idea] +- [ ] [Action to prototype] +- [ ] [Action to research] + +## Follow-up + +**Next meeting**: [Date to reconvene] +``` + diff --git a/skills/.curated/notion-meeting-intelligence/reference/decision-meeting-template.md b/skills/.curated/notion-meeting-intelligence/reference/decision-meeting-template.md new file mode 100644 index 0000000..5c0fa56 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/reference/decision-meeting-template.md @@ -0,0 +1,94 @@ +# Decision Meeting Template + +Use this template when you need to make an important decision with your team. + +```markdown +# [Decision Topic] - [Date] + +## Meeting Details +**Date & Time**: [Date and time] +**Duration**: [Length] +**Attendees**: [List of attendees with roles] +**Location**: [Physical location or video link] +**Facilitator**: [Name] + +## Pre-Read Summary + +### Background +[2-3 sentences providing context from related project pages] + +**Related Pages**: +- Project Overview +- Previous Discussion + +### Current Situation +[What brings us to this decision point] + +## Decision Required + +**Question**: [Clear statement of decision needed] + +**Timeline**: [When decision needs to be made] + +**Impact**: [Who/what is affected by this decision] + +## Options Analysis + +### Option A: [Name] +**Description**: [What this option entails] + +**Pros**: +- [Advantage] +- [Advantage] + +**Cons**: +- [Disadvantage] +- [Disadvantage] + +**Cost/Effort**: [Estimate] +**Risk**: [Risk assessment] + +### Option B: [Name] +[Repeat structure] + +### Option C: Do Nothing +**Description**: What happens if we don't decide +**Implications**: [Consequences] + +## Recommendation + +[If there is a recommended option, state it with rationale] + +## Discussion Topics + +1. [Topic to discuss] +2. [Clarification needed on] +3. [Trade-offs to consider] + +## Decision Framework + +**Criteria for evaluation**: +- [Criterion 1] +- [Criterion 2] +- [Criterion 3] + +## Decision + +[To be filled during meeting] + +**Selected Option**: [Option chosen] +**Rationale**: [Why] +**Owner**: [Who will implement] +**Timeline**: [When] + +## Action Items + +- [ ] [Action] - @[Owner] - Due: [Date] +- [ ] [Action] - @[Owner] - Due: [Date] + +## Follow-up + +**Next review**: [Date] +**Success metrics**: [How we'll know this worked] +``` + diff --git a/skills/.curated/notion-meeting-intelligence/reference/one-on-one-template.md b/skills/.curated/notion-meeting-intelligence/reference/one-on-one-template.md new file mode 100644 index 0000000..9885beb --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/reference/one-on-one-template.md @@ -0,0 +1,58 @@ +# 1:1 Meeting Template + +Use this template for manager/report one-on-one meetings. + +```markdown +# 1:1: [Manager] & [Report] - [Date] + +## Meeting Details +**Date**: [Date] +**Last meeting**: Previous 1:1 + +## Agenda + +### [Report]'s Topics +1. [Topic to discuss] +2. [Question or concern] + +### [Manager]'s Topics +1. [Topic to cover] +2. [Feedback or update] + +## Discussion Notes + +### [Topic 1] +[Discussion points] + +**Action items**: +- [ ] [Action] - @[Owner] + +### [Topic 2] +[Discussion points] + +## Career Development + +**Current focus**: [Development goal] +**Progress**: [Update on progress] + +## Feedback + +**What's going well**: +- [Positive feedback] + +**Areas for growth**: +- [Developmental feedback] + +## Action Items + +- [ ] [Action] - @[Report] - Due: [Date] +- [ ] [Action] - @[Manager] - Due: [Date] + +## Next Meeting + +**Date**: [Date] +**Topics to cover**: +- [Carry-over topic] +- [Upcoming topic] +``` + diff --git a/skills/.curated/notion-meeting-intelligence/reference/retrospective-template.md b/skills/.curated/notion-meeting-intelligence/reference/retrospective-template.md new file mode 100644 index 0000000..d3e3673 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/reference/retrospective-template.md @@ -0,0 +1,58 @@ +# Retrospective Template + +Use this template for sprint retrospectives and team retrospectives. + +```markdown +# Sprint [#] Retrospective - [Date] + +## Meeting Details +**Date**: [Date] +**Team**: [Team] +**Sprint**: [Sprint dates] +**Facilitator**: [Name] + +## Sprint Summary + +**Sprint Goal**: [Goal] +**Goal Met**: Yes / Partially / No + +**Completed**: [#] points +**Velocity**: [#] points +**Planned**: [#] points + +## Pre-Read + +**Sprint Metrics**: +- Tasks completed: [#] +- Tasks carried over: [#] +- Bugs found: [#] +- Blockers encountered: [#] + +## Discussion + +### What Went Well (Keep) + +[Team input during meeting] + +### What Didn't Go Well (Stop) + +[Team input during meeting] + +### What To Try (Start) + +[Team input during meeting] + +### Shout-outs + +[Team recognition] + +## Action Items + +- [ ] [Improvement to implement] - @[Owner] - Due: [Date] +- [ ] [Process change] - @[Owner] - Due: [Date] + +## Follow-up + +**Review actions in**: [Next retro date] +``` + diff --git a/skills/.curated/notion-meeting-intelligence/reference/sprint-planning-template.md b/skills/.curated/notion-meeting-intelligence/reference/sprint-planning-template.md new file mode 100644 index 0000000..36adb3b --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/reference/sprint-planning-template.md @@ -0,0 +1,68 @@ +# Sprint Planning Template + +Use this template for agile sprint planning meetings. + +```markdown +# Sprint [#] Planning - [Date] + +## Meeting Details +**Date**: [Date] +**Team**: [Team name] +**Sprint Duration**: [Dates] + +## Sprint Goal + +[Clear statement of what this sprint aims to accomplish] + +## Capacity + +| Team Member | Availability | Capacity (points) | +|-------------|--------------|-------------------| +| [Name] | [%] | [#] | +| **Total** | | [#] | + +## Backlog Review + +### High Priority Items + +[From product backlog, linked from task database] + +- Task 1 - [Points] +- Task 2 - [Points] + +## Sprint Backlog + +### Committed Items + +- [x] Task - [Points] - @[Owner] +- [ ] Task - [Points] - @[Owner] + +**Total committed**: [Points] + +### Stretch Goals + +- [ ] Task - [Points] + +## Dependencies & Risks + +**Dependencies**: +- [Dependency] + +**Risks**: +- [Risk] + +## Definition of Done + +- [ ] Code complete and reviewed +- [ ] Tests written and passing +- [ ] Documentation updated +- [ ] Deployed to staging +- [ ] QA approved + +## Next Steps + +- Team begins sprint work +- Daily standups at [Time] +- Sprint review on [Date] +``` + diff --git a/skills/.curated/notion-meeting-intelligence/reference/status-update-template.md b/skills/.curated/notion-meeting-intelligence/reference/status-update-template.md new file mode 100644 index 0000000..f5d8789 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/reference/status-update-template.md @@ -0,0 +1,74 @@ +# Status Update Meeting Template + +Use this template for regular project status updates and check-ins. + +```markdown +# [Project Name] Status Update - [Date] + +## Meeting Details +**Date**: [Date and time] +**Attendees**: [List] +**Project**: Project Page + +## Executive Summary + +**Status**: 🟢 On Track / 🟡 At Risk / 🔴 Behind + +**Progress**: [Percentage] complete +**Timeline**: [Status vs original plan] + +## Progress Since Last Meeting + +### Completed +- [Accomplishment with specifics] +- [Accomplishment with specifics] + +### In Progress +- [Work item and status] +- [Work item and status] + +## Metrics + +| Metric | Current | Target | Status | +|--------|---------|--------|--------| +| [Metric] | [Value] | [Value] | [Icon] | +| [Metric] | [Value] | [Value] | [Icon] | + +## Upcoming Work + +**Next 2 Weeks**: +- [Planned work] +- [Planned work] + +**Next Month**: +- [Milestone or major work] + +## Blockers & Risks + +### Active Blockers +- **[Blocker]**: [Description and impact] + - Action: [What's being done] + +### Risks +- **[Risk]**: [Description] + - Mitigation: [Strategy] + +## Discussion Topics + +1. [Topic requiring input] +2. [Topic for alignment] + +## Decisions Needed + +- [Decision] or None + +## Action Items + +- [ ] [Action] - @[Owner] - Due: [Date] + +## Next Meeting + +**Date**: [Date] +**Focus**: [What next meeting will cover] +``` + diff --git a/skills/.curated/notion-meeting-intelligence/reference/template-selection-guide.md b/skills/.curated/notion-meeting-intelligence/reference/template-selection-guide.md new file mode 100644 index 0000000..d528977 --- /dev/null +++ b/skills/.curated/notion-meeting-intelligence/reference/template-selection-guide.md @@ -0,0 +1,56 @@ +# Meeting Template Selection Guide + +Choose the right template for your meeting type. + +## Template Overview + +| Meeting Type | Use This Template | When to Use | +|--------------|-------------------|-------------| +| Make a decision | [Decision Meeting](decision-meeting-template.md) | Need to evaluate options and reach a decision | +| Project update | [Status Update](status-update-template.md) | Regular check-ins, progress reviews | +| Generate ideas | [Brainstorming](brainstorming-template.md) | Creative ideation, problem-solving | +| Sprint planning | [Sprint Planning](sprint-planning-template.md) | Planning agile sprint work | +| Sprint retro | [Retrospective](retrospective-template.md) | Reflecting on completed work | +| Manager/report | [1:1 Meeting](one-on-one-template.md) | Regular one-on-one check-ins | +| Weekly team sync | [Status Update](status-update-template.md) (simplified) | Routine team synchronization | + +## Quick Decision Tree + +``` +What's the primary purpose? + +├─ Make a decision +│ └─ Use: Decision Meeting Template +│ +├─ Update on progress +│ └─ Use: Status Update Template +│ +├─ Generate ideas +│ └─ Use: Brainstorming Template +│ +├─ Plan sprint work +│ └─ Use: Sprint Planning Template +│ +├─ Reflect on past work +│ └─ Use: Retrospective Template +│ +└─ Manager/report check-in + └─ Use: 1:1 Meeting Template +``` + +## Template Customization + +All templates can be customized: +- **Simplify** for shorter meetings +- **Add sections** for specific needs +- **Combine elements** from multiple templates +- **Adapt language** for your team culture + +## Best Practices + +1. **Choose template first**: Select before gathering context +2. **Gather Notion content**: Search and fetch relevant pages +3. **Enrich with research**: Add Codex insights where valuable +4. **Customize as needed**: Adapt template to specific situation +5. **Share early**: Give attendees time to review + diff --git a/skills/.curated/notion-research-documentation/LICENSE.txt b/skills/.curated/notion-research-documentation/LICENSE.txt new file mode 100644 index 0000000..0871708 --- /dev/null +++ b/skills/.curated/notion-research-documentation/LICENSE.txt @@ -0,0 +1,7 @@ +Copyright 2025 Notion Labs, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/skills/.curated/notion-research-documentation/SKILL.md b/skills/.curated/notion-research-documentation/SKILL.md new file mode 100644 index 0000000..80b1f7b --- /dev/null +++ b/skills/.curated/notion-research-documentation/SKILL.md @@ -0,0 +1,12 @@ +--- +name: notion-research-documentation +description: Research across Notion and synthesize into structured documentation; use when asked to research topics, create reports, or analyze information from Notion. +--- + +# Research & Documentation + +- Search for content using `Notion:notion-search` +- Fetch pages with `Notion:notion-fetch` +- Synthesize findings from multiple sources +- Create structured output with `Notion:notion-create-pages` +- See reference/format-selection-guide.md for output formats diff --git a/skills/.curated/notion-research-documentation/evaluations/README.md b/skills/.curated/notion-research-documentation/evaluations/README.md new file mode 100644 index 0000000..08ddcdd --- /dev/null +++ b/skills/.curated/notion-research-documentation/evaluations/README.md @@ -0,0 +1,109 @@ +# Research & Documentation Skill Evaluations + +Evaluation scenarios for testing the Research & Documentation skill across different Codex models. + +## Purpose + +These evaluations ensure the Research & Documentation skill: +- Searches across Notion workspace effectively +- Synthesizes information from multiple sources +- Selects appropriate research report format +- Creates comprehensive documentation with proper citations +- Works consistently across Haiku, Sonnet, and Opus + +## Evaluation Files + +### basic-research.json +Tests basic research workflow with synthesis across multiple Notion pages. + +**Scenario**: Research Q4 product roadmap and create summary +**Key Behaviors**: +- Searches Notion for roadmap-related pages +- Fetches multiple relevant pages (roadmap, product docs, meeting notes) +- Synthesizes information from different sources +- Selects appropriate format (Research Summary) +- Includes citations linking back to source pages +- Creates structured document with clear sections + +### research-to-database.json +Tests creating research documentation in a Notion database with properties. + +**Scenario**: Research competitor landscape and save to Research database +**Key Behaviors**: +- Searches for existing competitive intelligence in Notion +- Identifies Research database as target +- Fetches database schema to understand properties +- Creates page with correct property values (Research Type, Status, Date, etc.) +- Structures content with comparison format +- Includes source citations for both Notion pages and external research + +## Running Evaluations + +1. Enable the `research-documentation` skill +2. Submit the query from the evaluation file +3. Verify the skill searches Notion workspace comprehensively +4. Check that multiple source pages are fetched and synthesized +5. Verify appropriate format is selected (Research Summary, Comprehensive Report, Quick Brief, Comparison) +6. Confirm citations link back to sources +7. Test with Haiku, Sonnet, and Opus + +## Expected Skill Behaviors + +Research & Documentation evaluations should verify: + +### Notion Search & Synthesis +- Searches workspace with relevant queries +- Fetches multiple source pages (3-5+) +- Synthesizes information across sources +- Identifies patterns and insights +- Handles conflicting information appropriately + +### Format Selection +- Chooses correct format based on scope and depth: + - **Research Summary**: Quick overview with key findings + - **Comprehensive Report**: Deep analysis with multiple sections + - **Quick Brief**: Fast facts and takeaways + - **Comparison**: Side-by-side analysis +- Applies format structure consistently +- Uses appropriate sections and headings + +### Citation & Attribution +- Includes citations for all Notion sources +- Uses mention-page tags: `` +- Attributes findings to specific sources +- Distinguishes between Notion content and Codex research +- Links related documents + +### Document Quality +- Title clearly indicates research topic and date +- Executive summary or key findings upfront +- Organized with clear hierarchy +- Actionable insights and recommendations +- Appropriate depth for the query + +## Creating New Evaluations + +When adding Research & Documentation evaluations: + +1. **Test different research types** - Product research, competitive analysis, technical investigation, market research +2. **Vary source count** - Synthesis of 2-3 pages vs. 10+ pages +3. **Test format selection** - Does it choose the right format for the scope? +4. **Include database targets** - Not just standalone pages +5. **Test citation accuracy** - Are all sources properly attributed? +6. **Cross-workspace search** - Testing search across teamspaces if applicable + +## Example Success Criteria + +**Good** (specific, testable): +- "Searches Notion for 'roadmap' and 'Q4' and 'product'" +- "Fetches at least 3 different source pages" +- "Includes citation for each key finding using mention-page tags" +- "Creates page with title format 'Research: [Topic] - [Date]'" +- "Uses Research Summary format with sections: Executive Summary → Key Findings → Details → Recommendations → Sources" + +**Bad** (vague, untestable): +- "Searches Notion effectively" +- "Creates comprehensive research" +- "Uses sources appropriately" +- "Good documentation" + diff --git a/skills/.curated/notion-research-documentation/evaluations/basic-research.json b/skills/.curated/notion-research-documentation/evaluations/basic-research.json new file mode 100644 index 0000000..33a903f --- /dev/null +++ b/skills/.curated/notion-research-documentation/evaluations/basic-research.json @@ -0,0 +1,28 @@ +{ + "name": "Basic Research and Documentation", + "skills": ["research-documentation"], + "query": "Research our API authentication approach and create a summary document in Notion", + "expected_behavior": [ + "Searches Notion workspace for authentication-related pages using Notion:notion-search", + "Uses appropriate search terms like 'API authentication', 'auth', 'API security'", + "Applies filters if relevant (e.g., created_date_range, creator filters)", + "Fetches at least 2-3 relevant pages using Notion:notion-fetch to get detailed content", + "Analyzes the fetched content to extract key information about authentication approach", + "Creates a structured research summary document using Research Summary format (see reference/formats.md)", + "Includes sections: Executive Summary, Key Findings, Detailed Analysis, Recommendations, Sources", + "Cites source pages using tags for proper linking", + "Uses Notion:notion-create-pages to save the document to Notion", + "Applies Notion-flavored markdown with headings, bullets, and clear structure", + "Places document appropriately (asks user or uses project/research area)" + ], + "success_criteria": [ + "Document contains synthesized information from multiple searched pages", + "At least 2-3 source pages are cited with mention-page tags", + "Document follows Research Summary format structure from reference/formats.md", + "Title is descriptive with topic and date (e.g., 'API Authentication Research - Oct 2025')", + "Content is concise but comprehensive with clear findings", + "Uses Notion markdown correctly (headings, lists, mentions)", + "Document is placed in appropriate location or user is consulted" + ] +} + diff --git a/skills/.curated/notion-research-documentation/evaluations/research-to-database.json b/skills/.curated/notion-research-documentation/evaluations/research-to-database.json new file mode 100644 index 0000000..12b74be --- /dev/null +++ b/skills/.curated/notion-research-documentation/evaluations/research-to-database.json @@ -0,0 +1,29 @@ +{ + "name": "Research with Database Integration", + "skills": ["research-documentation"], + "query": "Research competitor pricing strategies and add to our Research database", + "expected_behavior": [ + "Searches for competitor and pricing information using Notion:notion-search", + "Applies appropriate search strategy (see reference/advanced-search.md patterns)", + "Fetches relevant pages using Notion:notion-fetch and synthesizes findings", + "Recognizes need to add to database (mentioned in query)", + "Searches for or asks about the Research database location", + "Fetches database using Notion:notion-fetch to get schema, data sources, and properties", + "Identifies correct data source from tags if multiple exist", + "Creates page with appropriate database properties (Type: Competitor Analysis, Category, Tags, Date, Status, etc.)", + "Uses parent: { data_source_id: 'collection://...' } for correct database placement", + "Includes research content using Competitor Analysis format (see reference/formats.md)", + "Sets all required properties from schema with correct values", + "Cites sources using mention-page tags per reference/citations.md" + ], + "success_criteria": [ + "Page is created in correct database using data_source_id as parent", + "All required database properties are set correctly", + "Property values match available options from fetched schema", + "Content follows Competitor Analysis format structure", + "Sources are cited with proper mention-page tags", + "Title is descriptive (e.g., 'Competitor Pricing Analysis')", + "Research synthesizes findings rather than just listing sources" + ] +} + diff --git a/skills/.curated/notion-research-documentation/examples/competitor-analysis.md b/skills/.curated/notion-research-documentation/examples/competitor-analysis.md new file mode 100644 index 0000000..31d0068 --- /dev/null +++ b/skills/.curated/notion-research-documentation/examples/competitor-analysis.md @@ -0,0 +1,283 @@ +# Example: Competitor Analysis + +## User Request + +> "Research competitor pricing models and create a comparison document" + +## Workflow Execution + +### Step 1: Search for Competitor Information + +``` +Notion:notion-search +query: "competitor pricing" +query_type: "internal" +filters: { + created_date_range: { + start_date: "2024-01-01" + } +} +``` + +**Results Found:** +- "Competitor Analysis - Stripe" (Product) +- "Market Research Q3 2024" (Strategy) +- "Pricing Strategy Discussion" (Product) +- "Competitor Feature Matrix" (Product) + +### Step 2: Fetch and Analyze + +``` +Notion:notion-fetch for each page +``` + +**Extracted Information:** + +**Stripe**: +- Pay-as-you-go: 2.9% + $0.30 per transaction +- No monthly fees +- Volume discounts available + +**Square**: +- Pay-as-you-go: 2.6% + $0.10 per transaction +- Monthly plan: $29/month with lower rates +- Hardware costs separate + +**PayPal**: +- Standard: 3.49% + $0.49 per transaction +- Advanced: $30/month + 2.59% + $0.49 +- Multi-currency fees + +**Adyen**: +- Interchange++ pricing model +- Custom enterprise pricing +- Setup and monthly fees apply + +### Step 3: Create Comparison Document + +``` +Notion:notion-create-pages + +pages: [{ + properties: { + "title": "Competitor Pricing Analysis - Payment Processors" + }, + content: "[Comparison document using template]" +}] +``` + +## Output Document + +```markdown +# Competitor Pricing Analysis - Payment Processors + +**Date**: October 14, 2025 +**Research Team**: Product Strategy + +## Executive Summary + +We analyzed four major payment processor competitors: Stripe, Square, PayPal, and Adyen. Pricing models vary from simple pay-as-you-go (Stripe) to complex interchange-plus (Adyen). Key insight: All competitors offer volume discounts for high-transaction merchants, with breakpoints typically at $100K/month processing volume. + +## Comparison Matrix + +| Feature | Stripe | Square | PayPal | Adyen | +|---------|--------|--------|--------|-------| +| **Base Rate** | 2.9% + $0.30 | 2.6% + $0.10 | 3.49% + $0.49 | Interchange++ | +| **Monthly Fee** | $0 | $0-29 | $0-30 | Custom | +| **Volume Discounts** | Yes, >$80K | Yes, >$250K | Yes, >$100K | Yes, custom | +| **Setup Fee** | $0 | $0 | $0 | $1,000-5,000 | +| **Multi-currency** | 1% extra | 3% extra | 3-4% extra | Included | +| **Chargeback Fee** | $15 | $15-25 | $20 | Custom | +| **Target Market** | Startups-Enterprise | Small-Medium | Small-Medium | Enterprise | + +## Detailed Analysis + +### Stripe + +**Pricing Structure**: +- **Standard**: 2.9% + $0.30 per successful card charge +- **Volume discounts**: Available for businesses processing >$80,000/month +- **International cards**: +1% fee +- **Currency conversion**: 1% above market rate + +**Strengths**: +- Simple, transparent pricing +- No setup fees or monthly minimums +- Excellent developer experience +- Quick onboarding + +**Weaknesses**: +- Higher per-transaction fee for high volume +- Volume discounts less aggressive than Adyen + +**Best for**: Startups and growth-stage companies needing quick integration + +**Source**: Competitor Analysis - Stripe + +### Square + +**Pricing Structure**: +- **Pay-as-you-go**: 2.6% + $0.10 per tap, dip, or swipe +- **Keyed-in**: 3.5% + $0.15 +- **Plus plan**: $29/month for lower rates (2.5% + $0.10) +- **Premium plan**: Custom pricing + +**Strengths**: +- Lowest per-transaction fee for in-person +- All-in-one hardware + software +- No long-term contracts + +**Weaknesses**: +- Higher rates for online/keyed transactions +- Hardware costs ($49-$299) +- Less suitable for online-only businesses + +**Best for**: Brick-and-mortar retail and restaurants + +**Source**: Market Research Q3 2024 + +### PayPal + +**Pricing Structure**: +- **Standard**: 3.49% + $0.49 per transaction +- **Advanced**: $30/month + 2.59% + $0.49 +- **Payments Pro**: Additional $30/month for direct credit card processing + +**Strengths**: +- Huge customer base (PayPal checkout) +- Buyer protection increases trust +- International reach (200+ countries) + +**Weaknesses**: +- Highest per-transaction fees +- Complex fee structure +- Account holds and reserves common + +**Best for**: Businesses where PayPal brand trust matters (e-commerce, marketplaces) + +**Source**: Pricing Strategy Discussion + +### Adyen + +**Pricing Structure**: +- **Interchange++**: Actual interchange + scheme fees + fixed markup +- **Setup fee**: $1,000-5,000 (negotiable) +- **Monthly minimum**: Typically $10,000+ processing volume +- **Per-transaction**: Interchange + 0.6% + $0.12 (example) + +**Strengths**: +- Most transparent cost structure at scale +- Lowest effective rate for high volume +- True multi-currency (100+ currencies) +- Direct connections to schemes + +**Weaknesses**: +- Complex pricing requires analysis +- High minimums ($10K+/month) +- Longer integration time +- Not suitable for small businesses + +**Best for**: Enterprise with $1M+/month processing volume + +**Source**: Competitor Feature Matrix + +## Pricing Trends & Insights + +### Volume-Based Discounting +All competitors offer discounts at scale: +- **Entry point**: $80K-$250K/month processing +- **Typical discount**: 10-30 basis points reduction +- **Negotiation leverage**: Begins at $500K/month+ + +### Hidden Costs to Consider + +| Cost Type | Stripe | Square | PayPal | Adyen | +|-----------|--------|--------|--------|-------| +| Chargeback | $15 | $15-25 | $20 | $15-25 | +| Account verification | $0 | $0 | $0 | Varies | +| PCI compliance | $0 | $0 | $0 | $0 | +| Currency conversion | 1% | 3% | 3-4% | 0% | +| Refund fees | Returned | Returned | Not returned | Varies | + +### Market Positioning + +``` +High Volume / Enterprise + ↑ + | Adyen + | + | Stripe + | + | Square PayPal + | + └──────────────────→ + Small / Simple Complex / International +``` + +## Strategic Implications + +### For Startups (<$100K/month) +**Recommended**: Stripe +- Lowest friction to start +- No upfront costs +- Great documentation +- Acceptable rates at this scale + +### For Growing Companies ($100K-$1M/month) +**Recommended**: Stripe or Square +- Negotiate volume discounts +- Evaluate interchange++ if international +- Consider Square if in-person dominant + +### For Enterprises (>$1M/month) +**Recommended**: Adyen or Negotiated Stripe +- Interchange++ models save significantly +- Direct scheme connections +- Multi-region capabilities matter +- ROI on integration complexity + +## Recommendations + +1. **Immediate**: Benchmark our current 2.8% + $0.25 against Stripe's standard +2. **Short-term**: Request volume discount quote from Stripe at our current $150K/month +3. **Long-term**: Evaluate Adyen when we cross $1M/month threshold + +## Next Steps + +- [ ] Request detailed pricing proposal from Stripe for volume discounts +- [ ] Create pricing calculator comparing all 4 at different volume levels +- [ ] Interview customers about payment method preferences +- [ ] Analyze our transaction mix (domestic vs international, card types) + +## Sources + +### Primary Research +- Competitor Analysis - Stripe +- Market Research Q3 2024 +- Pricing Strategy Discussion +- Competitor Feature Matrix + +### External References +- Stripe.com pricing page (Oct 2025) +- Square pricing documentation +- PayPal merchant fees +- Adyen pricing transparency report +``` + +## Key Success Factors + +1. **Structured comparison**: Matrix format for quick scanning +2. **Multiple dimensions**: Price, features, target market +3. **Strategic recommendations**: Not just data, but implications +4. **Visual elements**: Table and positioning diagram +5. **Actionable next steps**: Clear recommendations +6. **Comprehensive sources**: Internal research + external validation + +## Workflow Pattern Demonstrated + +- **Date-filtered search** (recent information only) +- **Multiple competitor synthesis** (4 different companies) +- **Comparison template** (matrix + detailed analysis) +- **Strategic layer** (implications and recommendations) +- **Action-oriented** (next steps included) + diff --git a/skills/.curated/notion-research-documentation/examples/market-research.md b/skills/.curated/notion-research-documentation/examples/market-research.md new file mode 100644 index 0000000..7dd8d57 --- /dev/null +++ b/skills/.curated/notion-research-documentation/examples/market-research.md @@ -0,0 +1,62 @@ +# Example: Market Research + +**User Request**: "Research the current state of AI coding assistants market and create a summary document in Notion" + +## Workflow + +### 1. Search +``` +Notion:notion-search +query: "AI coding assistants market" +``` +Found 3 relevant pages across Engineering, Strategy, and Product teamspaces. + +### 2. Fetch & Analyze +``` +Notion:notion-fetch (3x) +``` +Extracted market size, competitive landscape, technology trends from source pages. + +### 3. Create Documentation +``` +Notion:notion-create-pages +``` + +## Output (Condensed) + +```markdown +# AI Coding Assistants Market Research - Oct 2025 + +## Executive Summary +The AI coding assistant market is experiencing 150%+ YoY growth. GitHub Copilot dominates with 60% share, but specialized tools are gaining traction in specific niches. + +## Key Findings + +### Market Size and Growth +$800M in 2024 → $2.5B projected by 2026. Developer adoption: 23% (2023) → 47% (2024). +Source: Market Trends Q3 2025 + +### Competitive Landscape +- GitHub Copilot: 60% (strong IDE integration) +- Cursor: 15% (rapid growth, full IDE) +- Tabnine: 10% (enterprise, on-premise) +- Cody: 5% (codebase-aware) +- CodeWhisperer: 8% (AWS integration) +Source: AI Tools Competitive Analysis + +### Technology Trends +Key differentiators: context awareness, customization, multi-modal interfaces, code verification. +Source: Developer Tools Landscape + +## Next Steps +1. Monitor Cursor growth and feature releases +2. Evaluate Cody's codebase-aware capabilities +3. Document enterprise security/compliance requirements +4. Track pricing trends +``` + +## Key Takeaways +- Found relevant pages across multiple teamspaces +- Synthesized competitive, market, and technical perspectives +- Used proper citations linking to source pages +- Created actionable recommendations diff --git a/skills/.curated/notion-research-documentation/examples/technical-investigation.md b/skills/.curated/notion-research-documentation/examples/technical-investigation.md new file mode 100644 index 0000000..e2fded4 --- /dev/null +++ b/skills/.curated/notion-research-documentation/examples/technical-investigation.md @@ -0,0 +1,233 @@ +# Example: Technical Investigation + +## User Request + +> "Research our current caching strategy and create a technical summary" + +## Workflow Execution + +### Step 1: Search for Caching Information + +``` +Notion:notion-search +query: "caching strategy architecture" +query_type: "internal" +teamspace_id: "engineering-teamspace-id" +``` + +**Results Found:** +- "System Architecture Overview" (Engineering) +- "Redis Implementation Guide" (Backend Docs) +- "Performance Optimization - Q3 2024" (Engineering) +- "API Caching Decision Record" (Architecture) + +### Step 2: Fetch Relevant Pages + +``` +Notion:notion-fetch +id: "system-architecture-page-url" +``` + +Extracted: Current caching architecture uses Redis for API responses, Memcached for session storage. + +``` +Notion:notion-fetch +id: "redis-implementation-guide-url" +``` + +Extracted: Implementation details, TTL settings, invalidation strategies. + +``` +Notion:notion-fetch +id: "api-caching-decision-record-url" +``` + +Extracted: Why Redis was chosen over alternatives, trade-offs considered. + +### Step 3: Synthesize Findings + +**Key findings identified:** +- Two-tier caching: Redis (API responses) + Memcached (sessions) +- TTL strategy: 5 minutes for dynamic data, 1 hour for static +- Invalidation: Event-driven for critical updates +- Performance impact: 75% reduction in database load +- Known issues: Cache stampede on popular endpoints + +### Step 4: Create Technical Summary + +``` +Notion:notion-create-pages + +parent: { page_id: "engineering-docs-parent-id" } + +pages: [{ + properties: { + "title": "Technical Summary: Caching Strategy - Oct 2025" + }, + content: "[Structured technical summary using template]" +}] +``` + +## Output Document + +```markdown +# Technical Summary: Caching Strategy - Oct 2025 + +## Executive Summary + +Our caching infrastructure uses a two-tier approach with Redis for API response caching and Memcached for session management. This strategy has reduced database load by 75% and improved API response times from 200ms to 50ms average. + +## Architecture Overview + +### Layer 1: API Response Caching (Redis) +**Technology**: Redis 7.0 cluster (3 nodes) +**Purpose**: Cache GET endpoint responses +**TTL Strategy**: +- Dynamic content: 5 minutes +- Static content: 1 hour +- User-specific: 15 minutes + +**Source**: System Architecture Overview + +### Layer 2: Session Storage (Memcached) +**Technology**: Memcached 1.6 +**Purpose**: User session data, temporary state +**TTL**: 24 hours (session lifetime) + +## Implementation Details + +### Cache Key Format +``` +api:v1:{endpoint}:{params_hash} +session:{user_id}:{session_id} +``` + +### Invalidation Strategy +- **Event-driven**: Critical data changes trigger immediate invalidation +- **Time-based**: TTL expiration for non-critical data +- **Manual**: Admin tools for emergency cache clear + +**Source**: Redis Implementation Guide + +## Decision Rationale + +### Why Redis for API Caching? + +**Pros**: +- Advanced data structures (sorted sets, hashes) +- Built-in TTL with automatic eviction +- Pub/sub for cache invalidation events +- Persistence options for durability + +**Cons**: +- Higher memory usage than Memcached +- More complex cluster management + +**Decision**: Chosen for flexibility and rich feature set needed for API caching. + +**Source**: API Caching Decision Record + +### Why Memcached for Sessions? + +**Pros**: +- Simpler, lighter weight +- Excellent for key-value storage +- Lower memory footprint + +**Cons**: +- No persistence +- Limited data structures + +**Decision**: Perfect fit for ephemeral session data where simplicity is valued. + +## Performance Impact + +| Metric | Before Caching | After Caching | Improvement | +|--------|----------------|---------------|-------------| +| Avg Response Time | 200ms | 50ms | 75% faster | +| Database Load | 100% | 25% | 75% reduction | +| Cache Hit Rate | - | 85% | - | +| Peak RPS Handled | 1,000 | 4,000 | 4x increase | + +**Source**: Performance Optimization - Q3 2024 + +## Known Issues & Limitations + +### Cache Stampede +**Issue**: When popular cache entries expire, multiple requests hit database simultaneously + +**Mitigation**: Implemented probabilistic early expiration and request coalescing + +**Status**: Reduced by 90% but not eliminated + +### Stale Data Risk +**Issue**: Cached data can be up to TTL duration stale + +**Mitigation**: Event-driven invalidation for critical data paths + +**Status**: Acceptable trade-off for performance gains + +## Monitoring & Observability + +**Metrics tracked**: +- Cache hit/miss rates per endpoint +- Memory usage and eviction rates +- Response time distributions +- Invalidation event frequency + +**Tools**: DataDog dashboards, CloudWatch alarms + +## Future Considerations + +1. **Edge Caching**: Evaluate CDN integration for static assets +2. **Cache Warming**: Pre-populate cache for predictable traffic spikes +3. **Adaptive TTLs**: Adjust TTLs based on data change frequency +4. **Regional Caching**: Multi-region cache replication for global performance + +## Related Documentation + +- System Architecture Overview +- Redis Implementation Guide +- API Caching Decision Record +- Performance Optimization - Q3 2024 + +## Appendix: Configuration Examples + +### Redis Configuration +```yaml +maxmemory: 8gb +maxmemory-policy: allkeys-lru +tcp-keepalive: 60 +``` + +### Common Cache Operations +```python +# Set with TTL +cache.set(key, value, ttl=300) + +# Get with fallback +value = cache.get(key) or fetch_from_db(key) + +# Invalidate pattern +cache.delete_pattern("api:v1:users:*") +``` +``` + +## Key Success Factors + +1. **Multiple source integration**: Combined architecture docs, implementation guides, and decision records +2. **Technical depth**: Included configuration, code examples, metrics +3. **Decision context**: Explained why choices were made, not just what +4. **Practical focus**: Real performance numbers and known issues +5. **Future-looking**: Noted areas for improvement +6. **Well-cited**: Every major point links back to source material + +## Workflow Pattern Demonstrated + +This example shows the complete research workflow: +- **Scoped search** (teamspace filter for engineering) +- **Multi-page synthesis** (4 different sources) +- **Technical template** (architecture-focused format) +- **Proper placement** (under engineering docs) +- **Comprehensive citations** (links to all sources) + diff --git a/skills/.curated/notion-research-documentation/examples/trip-planning.md b/skills/.curated/notion-research-documentation/examples/trip-planning.md new file mode 100644 index 0000000..fb6d519 --- /dev/null +++ b/skills/.curated/notion-research-documentation/examples/trip-planning.md @@ -0,0 +1,128 @@ +# Example: Group Trip Research & Planning + +**User Request**: "Research and plan our friends' trip to Japan in March - we're 6 people looking for 10 days" + +## Workflow + +### 1. Search Existing Notes +``` +Notion:notion-search +query: "Japan travel" +``` +Found: Japan Travel Guide (from friend), Tokyo Restaurants, Kyoto Temple Guide + +### 2. Fetch & Extract Tips +``` +Notion:notion-fetch (3x) +``` +**Key info from previous travelers:** +- Best time: March-April (cherry blossoms) +- Must-see: Tokyo, Kyoto, Osaka +- Budget: $200-300/day (mid-range) +- Book accommodations 3 months ahead +- Get JR Pass before arrival +- Top restaurants: Sushi Dai, Ichiran Ramen, Tsunahachi Tempura + +### 3. Research & Synthesize +Combined previous traveler insights with: +- Flight options and prices +- Accommodation types (hotels/ryokans/Airbnb) +- Transportation (JR Pass essential) +- 10-day itinerary structure +- Budget breakdown + +### 4. Create Comprehensive Plan +``` +Notion:notion-create-pages +parent: { page_id: "travel-plans-parent-id" } +pages: [{ + properties: { + title: "Japan Trip 2026 - March 15-25 (10 Days)" + }, + content: "[Full trip plan with itinerary, budget, tips...]" +}] +``` + +## Output Sample + +```markdown +# Japan Trip 2026 - March 15-25 (10 Days) + +## Trip Overview +**Dates**: March 15-25, 2026 (Cherry Blossom Season 🌸) +**Group**: 6 people | **Budget**: $3,000-4,000/person + +## Itinerary Summary + +**Days 1-3: Tokyo** +- Arrive, explore Shibuya, Harajuku, Shinjuku +- Visit Tsukiji Market, Imperial Palace, Sensoji Temple +- Experience Tokyo nightlife, teamLab Borderless + +**Days 4-5: Hakone** +- Day trip from Tokyo +- Hot springs, Mt. Fuji views, Lake Ashi cruise + +**Days 6-8: Kyoto** +- Bullet train from Tokyo +- Fushimi Inari, Kinkaku-ji, Arashiyama Bamboo Grove +- Geisha district (Gion), traditional tea ceremony + +**Days 9-10: Osaka + Depart** +- Osaka Castle, Dotonbori food district +- Nara day trip (deer park, Todai-ji Temple) +- Return flight from Osaka (KIX) + +## Budget Breakdown (per person) +- **Flights**: $900-1,200 (round-trip) +- **Accommodations**: $700-1,000 (9 nights) +- **JR Pass**: $280 (7-day pass) +- **Food**: $500-700 ($50-70/day) +- **Activities**: $300-400 +- **Local transport**: $100 +**Total**: $2,780-3,680 + +## Key Bookings +- **Flights**: Book 3-4 months ahead +- **Hotels**: Book now (cherry blossom season) + - Tokyo: Shinjuku area (2 nights) + Asakusa (1 night) + - Kyoto: Gion area (3 nights) + - Osaka: Namba area (2 nights) +- **JR Pass**: Order 2-3 weeks before travel +- **Restaurants**: Reserve 1 week ahead (Sushi Dai, high-end spots) + +## Essential Tips +Source: Japan Travel Guide +- Get pocket WiFi or eSIM on arrival +- Download: Google Translate, Hyperdia (train routes), Tabelog (restaurants) +- Cash-heavy country - withdraw at 7-Eleven ATMs +- Shoes off in temples, ryokans, some restaurants +- Trains extremely punctual - don't be late +- Learn basic phrases: arigatou, sumimasen, itadakimasu + +## Packing List +- Comfortable walking shoes (10k+ steps/day) +- Light jacket (March 55-65°F) +- Backpack for day trips +- Cash pouch +- Portable charger + +## Next Steps +- [ ] Book flights (target: <$1,100/person) +- [ ] Order JR Passes +- [ ] Book hotels (Tokyo → Kyoto → Osaka) +- [ ] Create shared expense tracker +- [ ] Schedule group planning call + +## Sources +- Japan Travel Guide (Sarah's 2024 trip) +- Tokyo Restaurant Recommendations +- Kyoto Temple Guide +``` + +## Key Takeaways +- Leveraged previous traveler notes from Notion +- Combined personal insights with research +- Created actionable itinerary with budget breakdown +- Included practical tips from experienced travelers +- Set clear next steps for group coordination diff --git a/skills/.curated/notion-research-documentation/reference/advanced-search.md b/skills/.curated/notion-research-documentation/reference/advanced-search.md new file mode 100644 index 0000000..a555b1a --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/advanced-search.md @@ -0,0 +1,212 @@ +# Advanced Search Techniques + +## Search Filtering + +### By Date Range + +Use `created_date_range` to find recent content: + +``` +filters: { + created_date_range: { + start_date: "2024-01-01", + end_date: "2025-01-01" + } +} +``` + +**When to use**: +- Finding recent updates on a topic +- Focusing on current information +- Excluding outdated content + +### By Creator + +Use `created_by_user_ids` to find content from specific people: + +``` +filters: { + created_by_user_ids: ["user-id-1", "user-id-2"] +} +``` + +**When to use**: +- Research from subject matter experts +- Team-specific information +- Attribution tracking + +### Combined Filters + +Stack filters for precision: + +``` +filters: { + created_date_range: { + start_date: "2024-10-01" + }, + created_by_user_ids: ["expert-user-id"] +} +``` + +## Scoped Searches + +### Teamspace Scoping + +Restrict search to specific teamspace: + +``` +teamspace_id: "teamspace-uuid" +``` + +**When to use**: +- Project-specific research +- Department-focused information +- Reducing noise from irrelevant results + +### Page Scoping + +Search within a specific page and its subpages: + +``` +page_url: "https://notion.so/workspace/Page-Title-uuid" +``` + +**When to use**: +- Research within a project hierarchy +- Documentation updates +- Focused investigation + +### Database Scoping + +Search within a database's content: + +``` +data_source_url: "collection://data-source-uuid" +``` + +**When to use**: +- Task/project database research +- Structured data investigation +- Finding specific entries + +## Search Strategies + +### Broad to Narrow + +1. Start with general search term +2. Review results for relevant teamspaces/pages +3. Re-search with scope filters +4. Fetch detailed content from top results + +**Example**: +``` +Search 1: query="API integration" → 50 results across workspace +Search 2: query="API integration", teamspace_id="engineering" → 12 results +Fetch: Top 3-5 most relevant pages +``` + +### Multi-Query Approach + +Run parallel searches with related terms: + +``` +Query 1: "API integration" +Query 2: "API authentication" +Query 3: "API documentation" +``` + +Combine results to build comprehensive picture. + +### Temporal Research + +Search across time periods to track evolution: + +``` +Search 1: created_date_range 2023 → Historical context +Search 2: created_date_range 2024 → Recent developments +Search 3: created_date_range 2025 → Current state +``` + +## Result Processing + +### Identifying Relevant Results + +Look for: +- **High semantic match**: Result summary closely matches query intent +- **Recent updates**: Last-edited date is recent +- **Authoritative sources**: Created by known experts or in official locations +- **Comprehensive content**: Result summary suggests detailed information + +### Prioritizing Fetches + +Fetch pages in order of relevance: + +1. **Primary sources**: Direct documentation, official pages +2. **Recent updates**: Newly edited content +3. **Related context**: Supporting information +4. **Historical reference**: Background and context + +Don't fetch everything - be selective based on research needs. + +### Handling Too Many Results + +If search returns 20+ results: + +1. **Add filters**: Narrow by date, creator, or teamspace +2. **Refine query**: Use more specific terms +3. **Use page scoping**: Search within relevant parent page +4. **Sample strategically**: Fetch diverse results (recent, popular, authoritative) + +### Handling Too Few Results + +If search returns < 3 results: + +1. **Broaden query**: Use more general terms +2. **Remove filters**: Search full workspace +3. **Try synonyms**: Alternative terminology +4. **Search in related areas**: Adjacent teamspaces or pages + +## Search Quality + +### Effective Search Queries + +**Good queries** (specific, semantic): +- "Q4 product roadmap" +- "authentication implementation guide" +- "customer feedback themes" + +**Weak queries** (too vague): +- "roadmap" +- "guide" +- "feedback" + +**Over-specific queries** (too narrow): +- "Q4 2024 product roadmap for mobile app version 3.2 feature X" + +### User Context + +Always use available user context: +- Query should match their terminology +- Scope to their relevant teamspaces +- Consider their role/department +- Reference their recent pages + +## Connected Sources + +### Notion Integrations + +Search extends beyond Notion pages to: +- Slack messages (if connected) +- Google Drive documents (if connected) +- GitHub issues/PRs (if connected) +- Jira tickets (if connected) + +Be aware results may come from these sources. + +### Source Attribution + +When citing results from connected sources: +- Note the source type in documentation +- Use appropriate mention format +- Verify user has access to the source system + diff --git a/skills/.curated/notion-research-documentation/reference/citations.md b/skills/.curated/notion-research-documentation/reference/citations.md new file mode 100644 index 0000000..d3b2cff --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/citations.md @@ -0,0 +1,190 @@ +# Citation Styles + +## Basic Page Citation + +Always cite sources using Notion page mentions: + +```markdown +Page Title +``` + +The URL must be provided. The title is optional but improves readability: + +```markdown + +``` + +## Inline Citations + +Cite immediately after referenced information: + +```markdown +The Q4 revenue increased by 23% quarter-over-quarter (Q4 Financial Report). +``` + +## Multiple Sources + +When information comes from multiple sources: + +```markdown +Customer satisfaction has improved across all metrics (Q3 Survey Results, Support Analysis). +``` + +## Section-Level Citations + +For longer sections derived from one source: + +```markdown +### Engineering Priorities + +According to the Engineering Roadmap 2025: + +- Focus on API scalability +- Improve developer experience +- Migrate to microservices architecture +``` + +## Sources Section + +Always include a "Sources" section at document end: + +```markdown +## Sources + +- Strategic Plan 2025 +- Market Analysis Report +- Competitor Research: Q3 +- Customer Interview Notes +``` + +Group by category for long lists: + +```markdown +## Sources + +### Primary Sources +- Official Roadmap +- Strategy Document + +### Supporting Research +- Market Trends +- Customer Feedback + +### Background Context +- Historical Analysis +``` + +## Quoting Content + +When quoting directly from source: + +```markdown +The product team noted: "We need to prioritize mobile experience improvements" (Product Meeting Notes). +``` + +For block quotes: + +```markdown +> We need to prioritize mobile experience improvements to meet our Q4 goals. This includes performance optimization and UI refresh. +> +> — Product Meeting Notes - Oct 2025 +``` + +## Data Citations + +When presenting data, cite the source: + +```markdown +| Metric | Q3 | Q4 | Change | +|--------|----|----|--------| +| Revenue | $2.3M | $2.8M | +21.7% | +| Users | 12.4K | 15.1K | +21.8% | + +Source: Financial Dashboard +``` + +## Database Citations + +When referencing database content: + +```markdown +Based on analysis of the Projects Database, 67% of projects are on track. +``` + +## User Citations + +When attributing information to specific people: + +```markdown +Sarah Chen noted in Architecture Review that the microservices migration is ahead of schedule. +``` + +## Citation Frequency + +**Over-citing** (every sentence): +```markdown +The revenue increased (Report). +Costs decreased (Report). +Margin improved (Report). +``` + +**Under-citing** (no attribution): +```markdown +The revenue increased, costs decreased, and margin improved. +``` + +**Right balance** (grouped citation): +```markdown +The revenue increased, costs decreased, and margin improved (Q4 Financial Report). +``` + +## Outdated Information + +Note when source information might be outdated: + +```markdown +The original API design (API Spec v1, last updated January 2024) has been superseded by the new architecture in API Spec v2. +``` + +## Cross-References + +Link to related research documents: + +```markdown +## Related Research + +This research builds on previous findings: +- Market Analysis - Q2 2025 +- Competitor Landscape Review + +For implementation details, see: +- Technical Implementation Guide +``` + +## Citation Validation + +Before finalizing research: + +✓ Every key claim has a source citation +✓ All page mentions have valid URLs +✓ Sources section includes all cited pages +✓ Outdated sources are noted as such +✓ Direct quotes are clearly marked +✓ Data sources are attributed + +## Citation Style Consistency + +Choose one citation style and use throughout: + +**Inline style** (lightweight): +```markdown +Revenue grew 23% (Financial Report). Customer count increased 18% (Metrics Dashboard). +``` + +**Formal style** (full mentions): +```markdown +Revenue grew 23% (Q4 Financial Report). Customer count increased 18% (Metrics Dashboard). +``` + +**Recommend formal style** for most research documentation as it provides clickable navigation. + diff --git a/skills/.curated/notion-research-documentation/reference/comparison-format.md b/skills/.curated/notion-research-documentation/reference/comparison-format.md new file mode 100644 index 0000000..cfb31b7 --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/comparison-format.md @@ -0,0 +1,37 @@ +# Comparison Format + +**When to use**: +- Evaluating multiple options +- Tool/vendor selection +- Approach comparison +- Decision support + +## Characteristics + +**Length**: 800-1200 words typically + +**Structure**: +- Overview of what's being compared +- Comparison matrix table +- Detailed analysis per option (pros/cons) +- Clear recommendation with rationale +- Sources + +## Template + +See [comparison-template.md](comparison-template.md) for the full template. + +## Best For + +- Decision support with multiple options +- Tool or vendor selection +- Comparing different technical approaches +- Evaluating trade-offs between alternatives + +## Example Use Cases + +- "Compare the three database options discussed in our tech docs" +- "What are the pros and cons of each deployment approach?" +- "Compare the vendor proposals" +- "Evaluate the different authentication methods we've documented" + diff --git a/skills/.curated/notion-research-documentation/reference/comparison-template.md b/skills/.curated/notion-research-documentation/reference/comparison-template.md new file mode 100644 index 0000000..ce3c138 --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/comparison-template.md @@ -0,0 +1,44 @@ +# Comparison Template + +Use when researching multiple options or alternatives. See [comparison-format.md](comparison-format.md) for when to use this format. + +```markdown +# [Topic] Comparison + +## Overview +[Brief introduction to what's being compared and why] + +## Comparison Matrix + +| Criteria | Option A | Option B | Option C | +|----------|----------|----------|----------| +| [Criterion 1] | [Rating/Details] | [Rating/Details] | [Rating/Details] | +| [Criterion 2] | [Rating/Details] | [Rating/Details] | [Rating/Details] | + +## Detailed Analysis + +### Option A +**Pros**: +- [Advantage] +- [Advantage] + +**Cons**: +- [Disadvantage] +- [Disadvantage] + +**Best for**: [Use case] + +**Source**: Source Page + +[Repeat for each option] + +## Recommendation + +**Selected option**: [Choice] + +**Rationale**: [Why this option is best given the context] + +## Sources +[List all consulted pages] +``` + diff --git a/skills/.curated/notion-research-documentation/reference/comprehensive-report-format.md b/skills/.curated/notion-research-documentation/reference/comprehensive-report-format.md new file mode 100644 index 0000000..1422b2b --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/comprehensive-report-format.md @@ -0,0 +1,41 @@ +# Comprehensive Report Format + +**When to use**: +- Formal documentation requirements +- Strategic decision support +- Complex topics requiring extensive analysis +- Multiple stakeholders need alignment + +## Characteristics + +**Length**: 1500+ words + +**Structure**: +- Executive summary +- Background & context +- Methodology +- Detailed findings with subsections +- Data & evidence section +- Implications (short and long-term) +- Prioritized recommendations +- Appendix + +## Template + +See [comprehensive-report-template.md](comprehensive-report-template.md) for the full template. + +## Best For + +- Deep analysis and strategic decisions +- Formal documentation requirements +- Complex topics with multiple facets +- When stakeholders need extensive context +- Board presentations or executive briefings + +## Example Use Cases + +- "Create a comprehensive analysis of our market position" +- "Document the full technical investigation of the database migration" +- "Prepare an in-depth report on vendor options for executive review" +- "Analyze the pros and cons of different architectural approaches" + diff --git a/skills/.curated/notion-research-documentation/reference/comprehensive-report-template.md b/skills/.curated/notion-research-documentation/reference/comprehensive-report-template.md new file mode 100644 index 0000000..a49620f --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/comprehensive-report-template.md @@ -0,0 +1,64 @@ +# Comprehensive Report Template + +Use for in-depth research requiring extensive analysis. See [comprehensive-report-format.md](comprehensive-report-format.md) for when to use this format. + +```markdown +# [Report Title] + +## Executive Summary +[One paragraph summarizing the entire report] + +## Background & Context +[Why this research was conducted, what questions it addresses] + +## Methodology +- Sources consulted: [number] Notion pages across [teamspaces] +- Time period: [if relevant] +- Scope: [what was included/excluded] + +## Key Findings + +### [Major Theme 1] +**Summary**: [One sentence] + +**Details**: +- [Supporting point with evidence] +- [Supporting point with evidence] +- [Supporting point with evidence] + +**Sources**: [Page mentions] + +### [Major Theme 2] +[Repeat structure] + +## Data & Evidence + +[Tables, quotes, specific data points] + +## Implications + +### Short-term +[Immediate implications] + +### Long-term +[Strategic implications] + +## Recommendations + +### Priority 1: [High priority action] +- **What**: [Specific action] +- **Why**: [Rationale] +- **How**: [Implementation approach] + +### Priority 2: [Medium priority action] +[Repeat structure] + +## Appendix + +### Additional Resources +- [Related pages] + +### Open Questions +- [Unanswered questions for future research] +``` + diff --git a/skills/.curated/notion-research-documentation/reference/format-selection-guide.md b/skills/.curated/notion-research-documentation/reference/format-selection-guide.md new file mode 100644 index 0000000..87facda --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/format-selection-guide.md @@ -0,0 +1,95 @@ +# Format Selection Guide + +Choose the right output format for your research needs. + +## Decision Tree + +``` +Is this comparing multiple options? + ├─ YES → Use Comparison Format + └─ NO ↓ + +Is this time-sensitive or simple? + ├─ YES → Use Quick Brief + └─ NO ↓ + +Does this require formal/extensive documentation? + ├─ YES → Use Comprehensive Report + └─ NO → Use Research Summary (default) +``` + +## Format Overview + +| Format | Length | When to Use | Template | +|--------|--------|-------------|----------| +| [Research Summary](research-summary-format.md) | 500-1000 words | Most research requests (default) | [Template](research-summary-template.md) | +| [Comprehensive Report](comprehensive-report-format.md) | 1500+ words | Formal docs, strategic decisions | [Template](comprehensive-report-template.md) | +| [Quick Brief](quick-brief-format.md) | 200-400 words | Time-sensitive, simple topics | [Template](quick-brief-template.md) | +| [Comparison](comparison-format.md) | 800-1200 words | Evaluating options | [Template](comparison-template.md) | + +## Formatting Guidelines + +### Headings +- Use `#` for title +- Use `##` for major sections +- Use `###` for subsections +- Keep heading hierarchy consistent + +### Lists +- Use `-` for bullet points +- Use `1.` for numbered lists +- Keep list items parallel in structure + +### Emphasis +- Use `**bold**` for key terms and section labels +- Use `*italic*` for emphasis +- Use sparingly for maximum impact + +### Citations +- Always use `Page Title` for source pages +- Include citation immediately after referenced information +- Group all sources in a "Sources" section at the end + +### Tables +- Use for structured data comparison +- Keep columns to 3-5 for readability +- Include header row +- Align content appropriately + +### Code Blocks +Use when including: +- Technical specifications +- Configuration examples +- Command examples + +``` +Example code or configuration here +``` + +## Content Guidelines + +### Executive Summaries +- Lead with the most important finding +- Include 1-2 key implications +- Make it standalone (reader gets value without reading further) +- Target 2-3 sentences for summaries, 1 paragraph for reports + +### Key Findings +- Start with a clear headline +- Support with specific evidence +- Include relevant data points or quotes +- Cite source immediately +- Focus on actionable insights + +### Recommendations +- Make them specific and actionable +- Explain the "why" behind each recommendation +- Prioritize clearly (Priority 1, 2, 3 or High/Medium/Low) +- Include implementation hints when relevant + +### Source Citations +- Link to original pages using mentions +- Note if information is outdated (check last-edited dates) +- Credit specific sections when quoting +- Group related sources together + diff --git a/skills/.curated/notion-research-documentation/reference/quick-brief-format.md b/skills/.curated/notion-research-documentation/reference/quick-brief-format.md new file mode 100644 index 0000000..41ef5f2 --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/quick-brief-format.md @@ -0,0 +1,37 @@ +# Quick Brief Format + +**When to use**: +- Time-sensitive requests +- Simple topics +- Status updates +- Quick reference needs + +## Characteristics + +**Length**: 200-400 words + +**Structure**: +- 3-4 sentence summary +- 3-5 bullet key points +- Short action items list +- Brief source list + +## Template + +See [quick-brief-template.md](quick-brief-template.md) for the full template. + +## Best For + +- Fast turnaround requests +- Simple, straightforward topics +- Quick status updates +- When time is more important than depth +- Initial exploration before deeper research + +## Example Use Cases + +- "Quick summary of what's in our API docs" +- "Fast brief on the meeting notes from yesterday" +- "What are the key points from that spec?" +- "Give me a quick overview of the project status" + diff --git a/skills/.curated/notion-research-documentation/reference/quick-brief-template.md b/skills/.curated/notion-research-documentation/reference/quick-brief-template.md new file mode 100644 index 0000000..2b3f723 --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/quick-brief-template.md @@ -0,0 +1,25 @@ +# Quick Brief Template + +Use for fast turnaround requests or simple topics. See [quick-brief-format.md](quick-brief-format.md) for when to use this format. + +```markdown +# [Topic] - Quick Brief + +**Date**: [Current date] + +## Summary +[3-4 sentences covering the essentials] + +## Key Points +- **Point 1**: [Details] +- **Point 2**: [Details] +- **Point 3**: [Details] + +## Action Items +1. [Immediate next step] +2. [Follow-up action] + +## Sources +[Brief list of pages consulted] +``` + diff --git a/skills/.curated/notion-research-documentation/reference/research-summary-format.md b/skills/.curated/notion-research-documentation/reference/research-summary-format.md new file mode 100644 index 0000000..ce26657 --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/research-summary-format.md @@ -0,0 +1,33 @@ +# Research Summary Format + +**When to use**: General research requests, most common format + +## Characteristics + +**Length**: 500-1000 words typically + +**Structure**: +- Executive summary (2-3 sentences) +- 3-5 key findings with supporting evidence +- Detailed analysis section +- Conclusions and next steps +- Source citations + +## Template + +See [research-summary-template.md](research-summary-template.md) for the full template. + +## Best For + +- Most general-purpose research requests +- Standard documentation needs +- Balanced depth and readability +- When you need comprehensive but accessible information + +## Example Use Cases + +- "Research our authentication options" +- "What does our project documentation say about the API redesign?" +- "Summarize the team's discussion about mobile strategy" +- "Compile information about our deployment process" + diff --git a/skills/.curated/notion-research-documentation/reference/research-summary-template.md b/skills/.curated/notion-research-documentation/reference/research-summary-template.md new file mode 100644 index 0000000..9ebd156 --- /dev/null +++ b/skills/.curated/notion-research-documentation/reference/research-summary-template.md @@ -0,0 +1,49 @@ +# Research Summary Template + +Use this for most research requests. See [research-summary-format.md](research-summary-format.md) for when to use this format. + +```markdown +# [Topic Name] + +## Executive Summary +[2-3 sentence overview of key findings and implications] + +## Key Findings + +### Finding 1: [Clear headline] +[Details and supporting evidence] +- Source: Original Page + +### Finding 2: [Clear headline] +[Details and supporting evidence] +- Source: Original Page + +### Finding 3: [Clear headline] +[Details and supporting evidence] +- Source: Original Page + +## Detailed Analysis + +### [Section 1] +[In-depth discussion of first major theme] + +### [Section 2] +[In-depth discussion of second major theme] + +## Conclusions + +[Summary of implications and insights] + +## Next Steps + +1. [Actionable recommendation] +2. [Actionable recommendation] +3. [Actionable recommendation] + +## Sources + +- Page Title +- Page Title +- Page Title +``` + diff --git a/skills/.curated/notion-spec-to-implementation/LICENSE.txt b/skills/.curated/notion-spec-to-implementation/LICENSE.txt new file mode 100644 index 0000000..0871708 --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/LICENSE.txt @@ -0,0 +1,7 @@ +Copyright 2025 Notion Labs, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/skills/.curated/notion-spec-to-implementation/SKILL.md b/skills/.curated/notion-spec-to-implementation/SKILL.md new file mode 100644 index 0000000..f57dacd --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/SKILL.md @@ -0,0 +1,13 @@ +--- +name: notion-spec-to-implementation +description: Turn specs into implementation tasks for Codex; use when implementing specifications, breaking down requirements, or creating task lists from PRDs. +--- + +# Spec to Implementation + +- Find spec using `Notion:notion-search` +- Fetch and analyze with `Notion:notion-fetch` +- Create implementation plan with `Notion:notion-create-pages` +- Create tasks in task database +- Track progress with `Notion:notion-update-page` +- See reference/spec-parsing.md for requirement extraction patterns diff --git a/skills/.curated/notion-spec-to-implementation/evaluations/README.md b/skills/.curated/notion-spec-to-implementation/evaluations/README.md new file mode 100644 index 0000000..fe5399f --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/evaluations/README.md @@ -0,0 +1,120 @@ +# Spec to Implementation Skill Evaluations + +Evaluation scenarios for testing the Spec to Implementation skill across different Codex models. + +## Purpose + +These evaluations ensure the Spec to Implementation skill: +- Finds and parses specification pages accurately +- Breaks down specs into actionable implementation plans +- Creates tasks that Codex can implement with clear acceptance criteria +- Tracks progress and updates implementation status +- Works consistently across Haiku, Sonnet, and Opus + +## Evaluation Files + +### basic-spec-implementation.json +Tests basic workflow of turning a spec into an implementation plan. + +**Scenario**: Implement user authentication feature from spec +**Key Behaviors**: +- Searches for and finds the authentication spec page +- Fetches spec and extracts requirements +- Parses requirements into phases (setup, core features, polish) +- Creates implementation plan page linked to original spec +- Breaks down into clear phases with deliverables +- Includes timeline and dependencies + +### spec-to-tasks.json +Tests creating concrete tasks from a specification in a task database. + +**Scenario**: Create tasks from API redesign spec +**Key Behaviors**: +- Finds spec page in Notion +- Extracts specific requirements and acceptance criteria +- Searches for or creates task database +- Fetches task database schema +- Creates multiple tasks with proper properties (Status, Priority, Sprint, etc.) +- Each task has clear title, description, and acceptance criteria +- Tasks have dependencies where appropriate +- Links all tasks back to original spec + +## Running Evaluations + +1. Enable the `spec-to-implementation` skill +2. Submit the query from the evaluation file +3. Verify the skill finds the spec page via search +4. Check that requirements are accurately parsed +5. Confirm implementation plan is created with phases +6. Verify tasks have clear, implementable acceptance criteria +7. Check that tasks link back to spec +8. Test with Haiku, Sonnet, and Opus + +## Expected Skill Behaviors + +Spec to Implementation evaluations should verify: + +### Spec Discovery & Parsing +- Searches Notion for specification pages +- Fetches complete spec content +- Extracts all requirements accurately +- Identifies technical dependencies +- Understands acceptance criteria +- Notes any ambiguities or missing details + +### Implementation Planning +- Creates implementation plan page +- Breaks work into logical phases: + - Phase 1: Foundation/Setup + - Phase 2: Core Implementation + - Phase 3: Testing & Polish +- Includes timeline estimates +- Identifies dependencies between phases +- Links back to original spec + +### Task Creation +- Finds or identifies task database +- Fetches database schema for property names +- Creates tasks with correct properties +- Each task has: + - Clear, specific title + - Context and description + - Acceptance criteria (checklist format) + - Appropriate priority and status + - Link to spec page +- Tasks are right-sized (not too big, not too small) +- Dependencies between tasks are noted + +### Progress Tracking +- Implementation plan includes progress markers +- Tasks can be updated as work progresses +- Status updates link to completed work +- Blockers or changes are noted + +## Creating New Evaluations + +When adding Spec to Implementation evaluations: + +1. **Test different spec types** - Features, migrations, refactors, API changes, UI components +2. **Vary complexity** - Simple 1-phase vs. complex multi-phase implementations +3. **Test task granularity** - Does it create appropriately-sized tasks? +4. **Include edge cases** - Vague specs, conflicting requirements, missing details +5. **Test database integration** - Creating tasks in existing task databases with various schemas +6. **Progress tracking** - Updating implementation plans as tasks complete + +## Example Success Criteria + +**Good** (specific, testable): +- "Searches Notion for spec page using feature name" +- "Creates implementation plan with 3 phases: Setup → Core → Polish" +- "Creates 5-8 tasks in task database with properties: Task (title), Status, Priority, Sprint" +- "Each task has acceptance criteria in checklist format (- [ ] ...)" +- "Tasks link back to spec using mention-page tag" +- "Task titles are specific and actionable (e.g., 'Create login API endpoint' not 'Authentication')" + +**Bad** (vague, untestable): +- "Creates good implementation plan" +- "Tasks are well-structured" +- "Breaks down spec appropriately" +- "Links to spec" + diff --git a/skills/.curated/notion-spec-to-implementation/evaluations/basic-spec-implementation.json b/skills/.curated/notion-spec-to-implementation/evaluations/basic-spec-implementation.json new file mode 100644 index 0000000..9040751 --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/evaluations/basic-spec-implementation.json @@ -0,0 +1,32 @@ +{ + "name": "Create Implementation Plan from Spec", + "skills": ["spec-to-implementation"], + "query": "Create an implementation plan for the User Authentication spec page", + "expected_behavior": [ + "Step 1: Uses Notion:notion-search to find 'User Authentication spec' with keywords like 'User Authentication' or 'auth spec'", + "Step 2: If not found or ambiguous, asks user for spec page URL/ID", + "Step 3: Fetches spec page using Notion:notion-fetch with URL/ID from search results", + "Step 4: Parses spec using patterns from reference/spec-parsing.md to extract requirements, acceptance criteria, constraints", + "Step 5: Identifies functional requirements (user stories, features, workflows) and non-functional requirements (performance, security)", + "Step 6: Creates implementation plan following structure from reference/templates.md", + "Step 7: Includes sections: Overview, Linked Spec, Requirements Summary, Technical Approach, Implementation Phases", + "Step 8: Breaks work into logical phases with Goal, Tasks checklist, Estimated effort per phase", + "Step 9: Identifies dependencies and risks from spec content", + "Step 10: Links plan back to original spec page using ", + "Step 11: Creates plan page using Notion:notion-create-pages with appropriate title (e.g., 'Implementation Plan: User Authentication')", + "Step 12: Places plan appropriately (asks user or suggests under project/spec parent)" + ], + "success_criteria": [ + "Spec is found using Notion:notion-search before attempting to fetch (or user is asked for URL if not found)", + "Spec is fetched using Notion:notion-fetch with correct URL/ID from search results", + "Plan includes clear overview and spec link with mention-page tag", + "Requirements are extracted from actual spec content (not generic) using spec-parsing patterns", + "Work is broken into multiple phases (typically 3-5) following template structure", + "Each phase has Goal, Tasks (as checkboxes), and Estimated effort", + "Dependencies and risks sections are included with specific details from spec", + "Plan follows Implementation Plan structure from reference/templates.md", + "Success criteria or acceptance criteria from spec are referenced in plan", + "Uses correct tool names and sequence: Notion:notion-search → Notion:notion-fetch → Notion:notion-create-pages" + ] +} + diff --git a/skills/.curated/notion-spec-to-implementation/evaluations/spec-to-tasks.json b/skills/.curated/notion-spec-to-implementation/evaluations/spec-to-tasks.json new file mode 100644 index 0000000..4da86fb --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/evaluations/spec-to-tasks.json @@ -0,0 +1,35 @@ +{ + "name": "Create Tasks from Specification", + "skills": ["spec-to-implementation", "task-manager"], + "query": "Read the Payment Integration spec and create implementation tasks in our Tasks database", + "expected_behavior": [ + "Step 1: Uses Notion:notion-search to find Payment Integration spec or asks for URL", + "Step 2: Fetches spec page using Notion:notion-fetch to read full content", + "Step 3: Parses spec using reference/spec-parsing.md patterns to identify work items", + "Step 4: Breaks down into appropriately-sized tasks using breakdown patterns from reference/task-creation.md", + "Step 5: Uses Notion:notion-search to find Tasks database location", + "Step 6: Fetches Tasks database using Notion:notion-fetch to get schema, property names, and data sources", + "Step 7: Identifies correct data source from tags in fetch results", + "Step 8: Optionally creates implementation plan page first (recommended per workflow)", + "Step 9: For each task - creates task page using Notion:notion-create-pages with parent: { data_source_id: 'collection://...' }", + "Step 10: Sets task properties from schema: Title, Status (To Do), Priority, Related Tasks (link to spec)", + "Step 11: Includes task description with context, acceptance criteria from spec, dependencies", + "Step 12: Links tasks to spec page using and to each other for dependencies", + "Step 13: Sequences tasks appropriately (setup → implementation → testing per reference/task-creation.md)", + "Step 14: Reports summary: 'Created X tasks for Payment Integration: [task list with links]'" + ], + "success_criteria": [ + "Spec is found using Notion:notion-search before attempting to fetch", + "Task database is found using Notion:notion-search before attempting to fetch schema", + "Database schema is fetched and data source identified from tags", + "Multiple tasks created (at least 3-5) covering spec scope", + "Tasks are right-sized per reference/task-creation.md (1-2 days each)", + "Each task has clear acceptance criteria extracted from spec", + "Tasks are properly sequenced with dependencies using relation properties", + "All tasks link back to original spec using mention-page tags", + "Task properties match exact schema from fetched database", + "Tasks use correct parent (data_source_id: 'collection://...') for database placement", + "Uses correct tool names and sequence: Notion:notion-search (2x) → Notion:notion-fetch (2x) → Notion:notion-create-pages (Nx)" + ] +} + diff --git a/skills/.curated/notion-spec-to-implementation/examples/api-feature.md b/skills/.curated/notion-spec-to-implementation/examples/api-feature.md new file mode 100644 index 0000000..51df236 --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/examples/api-feature.md @@ -0,0 +1,461 @@ +# Example: API Feature Implementation + +## User Request + +> "Create an implementation plan for the User Profile API spec" + +## Workflow Execution + +### Step 1: Fetch Specification + +``` +Notion:notion-search +query: "User Profile API spec" +query_type: "internal" +``` + +Found: "User Profile API Specification" in Engineering Specs + +``` +Notion:notion-fetch +id: "user-profile-api-spec-page-id" +``` + +### Step 2: Parse Specification + +**Spec Content Extracted:** + +```markdown +# User Profile API Specification + +## Overview +RESTful API for user profile management + +## Requirements + +### Functional +- FR-1: Get user profile by ID +- FR-2: Update user profile (name, bio, avatar) +- FR-3: Upload profile avatar +- FR-4: Get user's public profile (limited fields) +- FR-5: Search users by name + +### Non-Functional +- NFR-1: Response time < 200ms (p95) +- NFR-2: Support 1000 concurrent users +- NFR-3: Avatar upload < 5MB +- NFR-4: GDPR compliant (data portability) + +## API Endpoints + +GET /api/v1/users/:id +PUT /api/v1/users/:id +POST /api/v1/users/:id/avatar +GET /api/v1/users/:id/public +GET /api/v1/users/search + +## Data Model +- id (UUID) +- email (string, unique) +- name (string) +- bio (text, max 500 chars) +- avatar_url (string) +- created_at (timestamp) +- updated_at (timestamp) + +## Security +- Authentication: JWT bearer token +- Authorization: Users can only update own profile +- Rate limiting: 100 req/min per user + +## Acceptance Criteria +- AC-1: All endpoints return proper HTTP status codes +- AC-2: Validation errors return 400 with error details +- AC-3: Unauthorized access returns 401 +- AC-4: Rate limit exceeded returns 429 +- AC-5: Avatar images stored in S3 +``` + +### Step 3: Create Implementation Plan + +``` +Notion:notion-create-pages + +parent: { page_id: "engineering-plans-parent-id" } + +pages: [{ + properties: { + "title": "Implementation Plan: User Profile API" + }, + content: "[Implementation plan]" +}] +``` + +**Implementation Plan Created:** + +```markdown +# Implementation Plan: User Profile API + +## Overview +Build RESTful API for user profile management with CRUD operations, avatar upload, and search functionality. + +## Linked Specification +User Profile API Specification + +## Requirements Summary + +### Functional Requirements +- ✅ Get user profile (authenticated) +- ✅ Update profile fields (name, bio) +- ✅ Upload avatar with image processing +- ✅ Public profile view (limited fields) +- ✅ User search by name + +### Non-Functional Requirements +- **Performance**: < 200ms response time (p95) +- **Scalability**: 1000 concurrent users +- **Storage**: Avatar files < 5MB to S3 +- **Compliance**: GDPR data portability + +### Acceptance Criteria +- All endpoints with proper status codes +- Input validation with error details +- JWT authentication required +- Rate limiting enforced +- Avatars stored in S3 + +## Technical Approach + +### Architecture +- **Framework**: Express.js (Node.js) +- **Database**: PostgreSQL +- **Storage**: AWS S3 for avatars +- **Cache**: Redis for profile data +- **Search**: PostgreSQL full-text search + +### Key Design Decisions +1. **JWT Authentication**: Stateless auth, scales horizontally +2. **S3 for Avatars**: Offload storage, CDN integration ready +3. **Redis Caching**: Reduce DB load for frequently accessed profiles +4. **Rate Limiting**: Token bucket algorithm, per-user limits + +## Implementation Phases + +### Phase 1: Foundation (Days 1-2) +**Goal**: Set up core infrastructure + +**Tasks**: +- [ ] Setup database schema +- [ ] Configure S3 bucket +- [ ] Setup Redis cache +- [ ] Create API scaffolding + +**Deliverables**: Working skeleton with DB, storage, cache ready +**Estimated effort**: 2 days + +### Phase 2: Core Endpoints (Days 3-5) +**Goal**: Implement main CRUD operations + +**Tasks**: +- [ ] Implement GET user profile +- [ ] Implement PUT update profile +- [ ] Add input validation +- [ ] Add JWT authentication middleware +- [ ] Implement rate limiting + +**Deliverables**: Working CRUD operations with auth +**Estimated effort**: 3 days + +### Phase 3: Avatar Upload (Days 6-7) +**Goal**: Avatar management with S3 + +**Tasks**: +- [ ] Implement avatar upload endpoint +- [ ] Add image validation (size, format) +- [ ] Process and resize images +- [ ] Upload to S3 with signed URLs + +**Deliverables**: Avatar upload/update functionality +**Estimated effort**: 2 days + +### Phase 4: Search & Public Profile (Days 8-9) +**Goal**: Complete remaining features + +**Tasks**: +- [ ] Implement user search +- [ ] Implement public profile endpoint +- [ ] Add search indexing +- [ ] Optimize search queries + +**Deliverables**: Search and public profiles working +**Estimated effort**: 2 days + +### Phase 5: Testing & Optimization (Days 10-12) +**Goal**: Production-ready quality + +**Tasks**: +- [ ] Write unit tests +- [ ] Write integration tests +- [ ] Performance testing +- [ ] Security audit +- [ ] API documentation + +**Deliverables**: Tested, documented, production-ready API +**Estimated effort**: 3 days + +## Dependencies + +### External Dependencies +- AWS S3 bucket created ✅ +- Redis instance available ✅ +- PostgreSQL database provisioned ✅ + +### Internal Dependencies +- JWT authentication service (exists) +- User database table (exists) +- Logging infrastructure (exists) + +### Blockers +None currently + +## Risks & Mitigation + +### Risk 1: Image Processing Performance +- **Probability**: Medium +- **Impact**: Medium +- **Mitigation**: Use background job queue for processing, return signed upload URL immediately + +### Risk 2: S3 Upload Failures +- **Probability**: Low +- **Impact**: Medium +- **Mitigation**: Implement retry logic with exponential backoff, fallback to local storage temporarily + +### Risk 3: Rate Limiting Complexity +- **Probability**: Low +- **Impact**: Low +- **Mitigation**: Use proven library (express-rate-limit with Redis store) + +### Risk 4: Search Performance +- **Probability**: Medium +- **Impact**: Medium +- **Mitigation**: Add database indexes, consider Elasticsearch if needed later + +## Timeline + +| Milestone | Target Date | Status | +|-----------|-------------|--------| +| Phase 1 Complete | Oct 16 | ⏳ Planned | +| Phase 2 Complete | Oct 19 | ⏳ Planned | +| Phase 3 Complete | Oct 21 | ⏳ Planned | +| Phase 4 Complete | Oct 23 | ⏳ Planned | +| Phase 5 Complete | Oct 26 | ⏳ Planned | +| **Production Deploy** | **Oct 28** | ⏳ Planned | + +**Total Duration**: 12 working days (~2.5 weeks) + +## Success Criteria + +### Technical Success +- [ ] All 5 endpoints implemented and working +- [ ] Response time < 200ms (p95) verified in load testing +- [ ] Handles 1000 concurrent users +- [ ] All acceptance criteria met +- [ ] Test coverage > 80% +- [ ] Security scan passed +- [ ] API documentation complete + +### Business Success +- [ ] User profile updates functional +- [ ] Avatar uploads working reliably +- [ ] Search returns relevant results in < 500ms +- [ ] Zero critical bugs in first week + +## Resources + +### Documentation +- User Profile API Specification (original spec) +- Authentication Service Docs +- AWS S3 Setup Guide + +### Related Work +- User Authentication API (similar pattern) +- File Upload Service (avatar upload reference) + +### External References +- Express.js best practices +- AWS S3 SDK documentation +- PostgreSQL full-text search guide + +## Progress Tracking + +### Phase Status +- Phase 1: ⏳ Not Started +- Phase 2: ⏳ Not Started +- Phase 3: ⏳ Not Started +- Phase 4: ⏳ Not Started +- Phase 5: ⏳ Not Started + +**Overall Progress**: 0% complete + +### Latest Update +*Implementation plan created on October 14, 2025* +``` + +### Step 4: Find Task Database + +``` +Notion:notion-search +query: "Tasks database" +query_type: "internal" +``` + +Found: "Engineering Tasks" database + +### Step 5: Fetch Task Database Schema + +``` +Notion:notion-fetch +id: "tasks-database-id" +``` + +**Schema retrieved:** +- Data source: `collection://tasks-db-uuid` +- Properties: Name (title), Status (select), Priority (select), Related Tasks (relation), Story Points (number), Tags (multi_select) + +### Step 6: Create Implementation Tasks + +Now create tasks for Phase 1: + +**Task 1: Setup database schema** + +``` +Notion:notion-create-pages + +parent: { data_source_id: "collection://tasks-db-uuid" } + +pages: [{ + properties: { + "Name": "Setup database schema for User Profile API", + "Status": "To Do", + "Priority": "High", + "Related Tasks": ["impl-plan-page-id", "spec-page-id"], + "Story Points": 3, + "Tags": "backend, database, api" + }, + content: "## Context\nImplementation task for User Profile API Specification\n\nPart of Implementation Plan: User Profile API - Phase 1\n\n## Objective\nCreate database schema for user profile storage\n\n## Requirements\nBased on spec data model:\n- id (UUID, primary key)\n- email (string, unique index)\n- name (string, not null)\n- bio (text, max 500 chars)\n- avatar_url (string, nullable)\n- created_at (timestamp)\n- updated_at (timestamp)\n\n## Acceptance Criteria\n- [ ] Migration file created\n- [ ] Schema includes all required fields\n- [ ] Indexes on email (unique) and name (search)\n- [ ] Constraints validated (bio length, email format)\n- [ ] Migration tested on dev database\n- [ ] Rollback migration created\n\n## Technical Approach\n```sql\nCREATE TABLE user_profiles (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n email VARCHAR(255) UNIQUE NOT NULL,\n name VARCHAR(255) NOT NULL,\n bio TEXT CHECK (length(bio) <= 500),\n avatar_url TEXT,\n created_at TIMESTAMP DEFAULT NOW(),\n updated_at TIMESTAMP DEFAULT NOW()\n);\n\nCREATE INDEX idx_user_profiles_email ON user_profiles(email);\nCREATE INDEX idx_user_profiles_name ON user_profiles USING gin(to_tsvector('english', name));\n```\n\n## Dependencies\n- Blocked By: None\n- Blocks: All Phase 2 tasks\n\n## Estimated Effort\n3 story points (half day)\n" +}] +``` + +*[Create similar tasks for all phases - 20 tasks total]* + +### Step 7: Link Plan Back to Spec + +``` +Notion:notion-update-page +page_id: "user-profile-api-spec-page-id" +command: "insert_content_after" +selection_with_ellipsis: "## Acceptance Criteria..." +new_str: " + +--- + +## Implementation + +**Implementation Plan**: Implementation Plan: User Profile API + +**Implementation Tasks**: See plan for full task breakdown (20 tasks across 5 phases) + +**Status**: Planning complete, ready to start implementation +" +``` + +## Summary Provided to User + +```markdown +## Implementation Plan Created ✅ + +### Plan Overview +- **Feature**: User Profile API +- **Duration**: 12 days (~2.5 weeks) +- **Phases**: 5 (Foundation → Core → Avatar → Search → Testing) +- **Tasks**: 20 tasks created +- **Target Launch**: October 28, 2025 + +### Implementation Phases + +**Phase 1: Foundation** (2 days) +- Database schema +- S3 and Redis setup +- API scaffolding + +**Phase 2: Core Endpoints** (3 days) +- GET/PUT user profile +- Authentication & validation +- Rate limiting + +**Phase 3: Avatar Upload** (2 days) +- Image upload & validation +- S3 integration +- Image processing + +**Phase 4: Search & Public Profile** (2 days) +- User search +- Public profile endpoint + +**Phase 5: Testing & Optimization** (3 days) +- Unit & integration tests +- Performance testing +- Documentation + +### Key Deliverables +- 5 REST API endpoints +- Avatar upload to S3 +- User search functionality +- Comprehensive tests +- API documentation + +### Links Created +✅ Plan page: Implementation Plan: User Profile API +✅ Spec updated with plan link +✅ 20 tasks created in task database +✅ All tasks linked to plan and spec + +### Next Steps +1. Review and approve plan +2. Assign tasks to team members +3. Begin Phase 1 (Foundation) +4. Daily standups for progress tracking + +**Ready to start implementation! 🚀** +``` + +## Key Features Demonstrated + +### Spec Parsing +- Extracted requirements (functional & non-functional) +- Identified API endpoints +- Noted data model +- Captured acceptance criteria +- Understood security requirements + +### Implementation Planning +- Broke into logical phases +- Sequenced work appropriately (foundation → features → testing) +- Identified dependencies +- Estimated effort per phase +- Created realistic timeline + +### Task Creation +- Generated 20 specific tasks +- Each task has context, acceptance criteria, technical approach +- Tasks link to both spec and plan +- Proper dependencies noted + +### Bidirectional Linking +- Plan links to spec +- Spec updated to link to plan +- Tasks link to both +- Easy navigation between all artifacts + +Perfect for: Feature implementation, API development, technical projects + diff --git a/skills/.curated/notion-spec-to-implementation/examples/database-migration.md b/skills/.curated/notion-spec-to-implementation/examples/database-migration.md new file mode 100644 index 0000000..32745fa --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/examples/database-migration.md @@ -0,0 +1,81 @@ +# Example: Database Migration Implementation + +**User Request**: "Plan and implement the database migration for user preferences schema" + +## Workflow + +### 1. Find & Fetch Spec +``` +Notion:notion-search → Found "User Preferences Schema Migration Spec" +Notion:notion-fetch → Extracted requirements +``` + +**Spec Summary**: Migrate from JSON blob to structured schema for better performance and data integrity. + +### 2. Parse Requirements +- **Current**: JSONB preferences column +- **Target**: Separate `user_preferences` and `notification_preferences` tables +- **Must maintain**: Backward compatibility during migration +- **Performance**: Support 1M+ users with zero downtime + +### 3. Create Implementation Plan +``` +Notion:notion-create-pages +pages: [{ + properties: { + title: "Implementation Plan: User Preferences Migration" + }, + content: "[Full implementation plan with phases]" +}] +``` + +**Plan included**: +- **Phase 1**: Create new tables with indexes +- **Phase 2**: Backfill data from JSONB +- **Phase 3**: Dual-write mode (both old and new) +- **Phase 4**: Switch reads to new schema +- **Phase 5**: Drop old JSONB column + +### 4. Find Task Database & Create Tasks +``` +Notion:notion-search → Found "Engineering Tasks" database +Notion:notion-fetch → Got schema (Task, Status, Priority, Assignee, etc.) + +Notion:notion-create-pages +parent: { data_source_id: "collection://xyz" } +pages: [ + { + properties: { + "Task": "Write migration SQL scripts", + "Status": "To Do", + "Priority": "High", + "Sprint": "Sprint 25" + }, + content: "## Context\nPart of User Preferences Migration...\n\n## Acceptance Criteria\n- [ ] Migration script creates tables\n- [ ] Indexes defined..." + }, + // ... 4 more tasks +] +``` + +**Tasks created**: +1. Write migration SQL scripts +2. Implement backfill job +3. Add dual-write logic to API +4. Update read queries +5. Rollback plan & monitoring + +### 5. Track Progress +Regular updates to implementation plan with status, blockers, and completion notes. + +## Key Outputs + +**Implementation Plan Page** (linked to spec) +**5 Tasks in Database** (with dependencies, acceptance criteria) +**Progress Tracking** (updated as work progresses) + +## Success Factors +- Broke down complex migration into clear phases +- Created tasks with specific acceptance criteria +- Established dependencies (Phase 1 → 2 → 3 → 4 → 5) +- Zero-downtime approach with rollback plan +- Linked all work back to original spec diff --git a/skills/.curated/notion-spec-to-implementation/examples/ui-component.md b/skills/.curated/notion-spec-to-implementation/examples/ui-component.md new file mode 100644 index 0000000..7600942 --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/examples/ui-component.md @@ -0,0 +1,68 @@ +# Example: UI Component Implementation + +**User Request**: "Implement the new search component from the design spec" + +## Workflow + +### 1. Find Spec +``` +Notion:notion-search +query: "search component design spec" +``` +Found: "Global Search Redesign Spec" + +### 2. Fetch & Parse Spec +``` +Notion:notion-fetch +``` + +**Requirements**: +- Instant search with debounced API calls +- Keyboard navigation (↑↓ arrows, Enter, Esc) +- Recent searches history +- Result categories (pages, people, files) +- Mobile responsive +- Accessibility (ARIA labels, screen reader) + +### 3. Create Implementation Plan +``` +Notion:notion-create-pages +``` + +**Plan phases**: +- Phase 1: Base component structure +- Phase 2: API integration & debouncing +- Phase 3: Keyboard navigation +- Phase 4: Recent searches +- Phase 5: Polish & accessibility + +### 4. Create Tasks +``` +Notion:notion-create-pages (7 tasks) +``` + +**Tasks**: +1. Create SearchInput component +2. Implement useDebounce hook +3. Add keyboard navigation +4. LocalStorage for recent searches +5. Result categorization UI +6. Accessibility audit +7. Mobile responsive styling + +### 5. Implement & Track +As each task completed, updated status and added progress notes with screenshots and implementation details. + +## Key Outputs + +**Implementation Plan** (linked to design spec) +**7 Component Tasks** (in Engineering Tasks database) +**Progress Updates** (with code snippets and demo links) + +## Success Factors +- Clear component breakdown +- Separated concerns (logic, UI, accessibility) +- Each task had acceptance criteria +- Referenced design spec throughout +- Included accessibility from start, not afterthought +- Tracked progress with visual updates diff --git a/skills/.curated/notion-spec-to-implementation/reference/milestone-summary-template.md b/skills/.curated/notion-spec-to-implementation/reference/milestone-summary-template.md new file mode 100644 index 0000000..807cbe2 --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/reference/milestone-summary-template.md @@ -0,0 +1,27 @@ +# Milestone Summary Template + +Use this when completing major phases or milestones. + +```markdown +## Phase [N] Complete: [Date] + +### Accomplishments +- [Major item delivered] +- [Major item delivered] + +### Deliverables +- Deliverable 1 +- [Link to PR/deployment] + +### Metrics +- [Relevant metric] +- [Relevant metric] + +### Learnings +- [What went well] +- [What to improve] + +### Next Phase +Starting [Phase name] on [Date] +``` + diff --git a/skills/.curated/notion-spec-to-implementation/reference/progress-tracking.md b/skills/.curated/notion-spec-to-implementation/reference/progress-tracking.md new file mode 100644 index 0000000..14b0061 --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/reference/progress-tracking.md @@ -0,0 +1,458 @@ +# Progress Tracking + +## Update Frequency + +### Daily Updates + +For active implementation work: + +**What to update**: +- Task status if changed +- Add progress note to task +- Update blockers + +**When**: +- End of work day +- After completing significant work +- When encountering blockers + +### Milestone Updates + +For phase/milestone completion: + +**What to update**: +- Mark phase complete in plan +- Add milestone summary +- Update timeline if needed +- Report to stakeholders + +**When**: +- Phase completion +- Major deliverable ready +- Sprint end +- Release + +### Status Change Updates + +For task state transitions: + +**What to update**: +- Task status property +- Add transition note +- Notify relevant people + +**When**: +- Start work (To Do → In Progress) +- Ready for review (In Progress → In Review) +- Complete (In Review → Done) +- Block (Any → Blocked) + +## Progress Note Format + +### Daily Progress Note + +```markdown +## Progress: [Date] + +### Completed +- [Specific accomplishment with details] +- [Specific accomplishment with details] + +### In Progress +- [Current work item] +- Current status: [Percentage or description] + +### Next Steps +1. [Next planned action] +2. [Next planned action] + +### Blockers +- [Blocker description and who/what needed to unblock] +- Or: None + +### Decisions Made +- [Any technical/product decisions] + +### Notes +[Additional context, learnings, issues encountered] +``` + +Example: + +```markdown +## Progress: Oct 14, 2025 + +### Completed +- Implemented user authentication API endpoints (login, logout, refresh) +- Added JWT token generation and validation +- Wrote unit tests for auth service (95% coverage) + +### In Progress +- Frontend login form integration +- Currently: Form submits but need to handle error states + +### Next Steps +1. Complete error handling in login form +2. Add loading states +3. Implement "remember me" functionality + +### Blockers +None + +### Decisions Made +- Using HttpOnly cookies for refresh tokens (more secure than localStorage) +- Session timeout set to 24 hours based on security review + +### Notes +- Found edge case with concurrent login attempts, added to backlog +- Performance of auth check is good (<10ms) +``` + +### Milestone Summary + +```markdown +## Phase [N] Complete: [Date] + +### Overview +[Brief description of what was accomplished in this phase] + +### Completed Tasks +- Task 1 ✅ +- Task 2 ✅ +- Task 3 ✅ + +### Deliverables +- [Deliverable 1]: [Link/description] +- [Deliverable 2]: [Link/description] + +### Key Accomplishments +- [Major achievement] +- [Major achievement] + +### Metrics +- [Relevant metric]: [Value] +- [Relevant metric]: [Value] + +### Challenges Overcome +- [Challenge and how it was solved] + +### Learnings +**What went well**: +- [Success factor] + +**What to improve**: +- [Area for improvement] + +### Impact on Timeline +- On schedule / [X days ahead/behind] +- Reason: [If deviation, explain why] + +### Next Phase +- **Starting**: [Next phase name] +- **Target start date**: [Date] +- **Focus**: [Main objectives] +``` + +## Updating Implementation Plan + +### Progress Indicators + +Update plan page regularly: + +```markdown +## Status Overview + +**Overall Progress**: 45% complete + +### Phase Status +- ✅ Phase 1: Foundation - Complete +- 🔄 Phase 2: Core Features - In Progress (60%) +- ⏳ Phase 3: Integration - Not Started + +### Task Summary +- ✅ Completed: 12 tasks +- 🔄 In Progress: 5 tasks +- 🚧 Blocked: 1 task +- ⏳ Not Started: 8 tasks + +**Last Updated**: [Date] +``` + +### Task Checklist Updates + +Mark completed tasks: + +```markdown +## Implementation Phases + +### Phase 1: Foundation +- [x] Database schema +- [x] API scaffolding +- [x] Auth setup + +### Phase 2: Core Features +- [x] User management +- [ ] Dashboard +- [ ] Reporting +``` + +### Timeline Updates + +Update milestone dates: + +```markdown +## Timeline + +| Milestone | Original | Current | Status | +|-----------|----------|---------|--------| +| Phase 1 | Oct 15 | Oct 14 | ✅ Complete (1 day early) | +| Phase 2 | Oct 30 | Nov 2 | 🔄 In Progress (3 days delay) | +| Phase 3 | Nov 15 | Nov 18 | ⏳ Planned (adjusted) | +| Launch | Nov 20 | Nov 22 | ⏳ Planned (adjusted) | + +**Timeline Status**: Slightly behind due to [reason] +``` + +## Task Status Tracking + +### Status Definitions + +**To Do**: Not started +- Task is ready to begin +- Dependencies met +- Assigned (or available) + +**In Progress**: Actively being worked +- Work has started +- Assigned to someone +- Regular updates expected + +**Blocked**: Cannot proceed +- Dependency not met +- External blocker +- Waiting on decision/resource + +**In Review**: Awaiting review +- Work complete from implementer perspective +- Needs code review, QA, or approval +- Reviewers identified + +**Done**: Complete +- All acceptance criteria met +- Reviewed and approved +- Deployed/delivered + +### Updating Task Status + +When updating: + +``` +1. Update Status property +2. Add progress note explaining change +3. Update related tasks if needed +4. Notify relevant people via comment + +Example: +properties: { "Status": "In Progress" } + +Content update: +## Progress: Oct 14, 2025 +Started implementation. Set up basic structure and wrote initial tests. +``` + +## Blocker Tracking + +### Recording Blockers + +When encountering a blocker: + +```markdown +## Blockers + +### [Date]: [Blocker Description] +**Status**: 🚧 Active +**Impact**: [What's blocked] +**Needed to unblock**: [Action/person/decision needed] +**Owner**: [Who's responsible for unblocking] +**Target resolution**: [Date or timeframe] +``` + +### Resolving Blockers + +When unblocked: + +```markdown +## Blockers + +### [Date]: [Blocker Description] +**Status**: ✅ Resolved on [Date] +**Resolution**: [How it was resolved] +**Impact**: [Any timeline/scope impact] +``` + +### Escalating Blockers + +If blocker needs escalation: + +``` +1. Update blocker status in task +2. Add comment tagging stakeholder +3. Update plan with blocker impact +4. Propose mitigation if possible +``` + +## Metrics Tracking + +### Velocity Tracking + +Track completion rate: + +```markdown +## Velocity + +### Week 1 +- Tasks completed: 8 +- Story points: 21 +- Velocity: Strong + +### Week 2 +- Tasks completed: 6 +- Story points: 18 +- Velocity: Moderate (1 blocker) + +### Week 3 +- Tasks completed: 9 +- Story points: 24 +- Velocity: Strong (blocker resolved) +``` + +### Quality Metrics + +Track quality indicators: + +```markdown +## Quality Metrics + +- Test coverage: 87% +- Code review approval rate: 95% +- Bug count: 3 (2 minor, 1 cosmetic) +- Performance: All targets met +- Security: No issues found +``` + +### Progress Metrics + +Quantitative progress: + +```markdown +## Progress Metrics + +- Requirements implemented: 15/20 (75%) +- Acceptance criteria met: 42/56 (75%) +- Test cases passing: 128/135 (95%) +- Code complete: 80% +- Documentation: 60% +``` + +## Stakeholder Communication + +### Weekly Status Report + +```markdown +## Weekly Status: [Week of Date] + +### Summary +[One paragraph overview of progress and status] + +### This Week's Accomplishments +- [Key accomplishment] +- [Key accomplishment] +- [Key accomplishment] + +### Next Week's Plan +- [Planned work] +- [Planned work] + +### Status +- On track / At risk / Behind schedule +- [If at risk or behind, explain and provide mitigation plan] + +### Blockers & Needs +- [Active blocker or need for help] +- Or: None + +### Risks +- [New or evolving risk] +- Or: None currently identified +``` + +### Executive Summary + +For leadership updates: + +```markdown +## Implementation Status: [Feature Name] + +**Overall Status**: 🟢 On Track / 🟡 At Risk / 🔴 Behind + +**Progress**: [X]% complete + +**Key Updates**: +- [Most important update] +- [Most important update] + +**Timeline**: [Status vs original plan] + +**Risks**: [Top 1-2 risks] + +**Next Milestone**: [Upcoming milestone and date] +``` + +## Automated Progress Tracking + +### Query-Based Status + +Generate status from task database: + +``` +Query task database: +SELECT + "Status", + COUNT(*) as count +FROM "collection://tasks-uuid" +WHERE "Related Tasks" CONTAINS 'plan-page-id' +GROUP BY "Status" + +Generate summary: +- To Do: 8 +- In Progress: 5 +- Blocked: 1 +- In Review: 2 +- Done: 12 + +Overall: 44% complete (12/28 tasks) +``` + +### Timeline Calculation + +Calculate projected completion: + +``` +Average velocity: 6 tasks/week +Remaining tasks: 14 +Projected completion: 2.3 weeks from now + +Compares to target: [On schedule/Behind/Ahead] +``` + +## Best Practices + +1. **Update regularly**: Don't let updates pile up +2. **Be specific**: "Completed login" vs "Made progress" +3. **Quantify progress**: Use percentages, counts, metrics +4. **Note blockers immediately**: Don't wait to report blockers +5. **Link to work**: Reference PRs, deployments, demos +6. **Track decisions**: Document why, not just what +7. **Be honest**: Report actual status, not optimistic status +8. **Update in one place**: Keep implementation plan as source of truth + diff --git a/skills/.curated/notion-spec-to-implementation/reference/progress-update-template.md b/skills/.curated/notion-spec-to-implementation/reference/progress-update-template.md new file mode 100644 index 0000000..70a2f0b --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/reference/progress-update-template.md @@ -0,0 +1,25 @@ +# Progress Update Template + +Use this to update progress on implementation plans and tasks. + +```markdown +## Progress: [Date] + +### Completed Today +- [Specific item completed] +- [Specific item completed] + +### In Progress +- [Current work item and status] + +### Next Steps +1. [Next action] +2. [Next action] + +### Blockers +- [Blocker description] or None + +### Notes +[Additional context, decisions made, issues encountered] +``` + diff --git a/skills/.curated/notion-spec-to-implementation/reference/quick-implementation-plan.md b/skills/.curated/notion-spec-to-implementation/reference/quick-implementation-plan.md new file mode 100644 index 0000000..be42908 --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/reference/quick-implementation-plan.md @@ -0,0 +1,26 @@ +# Quick Implementation Plan Template + +For simpler features or small changes. + +```markdown +# Implementation: [Feature Name] + +## Spec +Specification + +## Summary +[Quick description] + +## Tasks +- [ ] Task 1 +- [ ] Task 2 +- [ ] Task 3 + +## Timeline +Start: [Date] +Target completion: [Date] + +## Status +[Update as work progresses] +``` + diff --git a/skills/.curated/notion-spec-to-implementation/reference/spec-parsing.md b/skills/.curated/notion-spec-to-implementation/reference/spec-parsing.md new file mode 100644 index 0000000..e60a3cf --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/reference/spec-parsing.md @@ -0,0 +1,383 @@ +# Specification Parsing + +## Finding the Specification + +Before parsing, locate the spec page: + +``` +1. Search for spec: + Notion:notion-search + query: "[Feature Name] spec" or "[Feature Name] specification" + +2. Handle results: + - If found → use page URL/ID + - If multiple → ask user which one + - If not found → ask user for URL/ID + +Example: +Notion:notion-search +query: "User Profile API spec" +query_type: "internal" +``` + +## Reading Specifications + +After finding the spec, fetch it with `Notion:notion-fetch`: + +1. Read the full content +2. Identify key sections +3. Extract structured information +4. Note ambiguities or gaps + +``` +Notion:notion-fetch +id: "spec-page-id-from-search" +``` + +## Common Spec Structures + +### Requirements-Based Spec + +``` +# Feature Spec +## Overview +[Feature description] + +## Requirements +### Functional +- REQ-1: [Requirement] +- REQ-2: [Requirement] + +### Non-Functional +- PERF-1: [Performance requirement] +- SEC-1: [Security requirement] + +## Acceptance Criteria +- AC-1: [Criterion] +- AC-2: [Criterion] +``` + +Extract: +- List of functional requirements +- List of non-functional requirements +- List of acceptance criteria + +### User Story Based Spec + +``` +# Feature Spec +## User Stories +### As a [user type] +I want [goal] +So that [benefit] + +**Acceptance Criteria**: +- [Criterion] +- [Criterion] +``` + +Extract: +- User personas +- Goals/capabilities needed +- Acceptance criteria per story + +### Technical Design Doc + +``` +# Technical Design +## Problem Statement +[Problem description] + +## Proposed Solution +[Solution approach] + +## Architecture +[Architecture details] + +## Implementation Plan +[Implementation approach] +``` + +Extract: +- Problem being solved +- Proposed solution approach +- Architectural decisions +- Implementation guidance + +### Product Requirements Document (PRD) + +``` +# PRD: [Feature] +## Goals +[Business goals] + +## User Needs +[User problems being solved] + +## Features +[Feature list] + +## Success Metrics +[How to measure success] +``` + +Extract: +- Business goals +- User needs +- Feature list +- Success metrics + +## Extraction Strategies + +### Requirement Identification + +Look for: +- "Must", "Should", "Will" statements +- Numbered requirements (REQ-1, etc.) +- User stories (As a... I want...) +- Acceptance criteria sections +- Feature lists + +### Categorization + +Group requirements by: + +**Functional**: What the system does +- User capabilities +- System behaviors +- Data operations + +**Non-Functional**: How the system performs +- Performance targets +- Security requirements +- Scalability needs +- Availability requirements +- Compliance requirements + +**Constraints**: Limitations +- Technical constraints +- Business constraints +- Timeline constraints + +### Priority Extraction + +Identify priority indicators: +- "Critical", "Must have", "P0" +- "Important", "Should have", "P1" +- "Nice to have", "Could have", "P2" +- "Future", "Won't have", "P3" + +Map to implementation phases based on priority. + +## Handling Ambiguity + +### Unclear Requirements + +When requirement is ambiguous: + +```markdown +## Clarifications Needed + +### [Requirement ID/Description] +**Current text**: "[Ambiguous requirement]" +**Question**: [What needs clarification] +**Impact**: [Why this matters for implementation] +**Assumed for now**: [Working assumption if any] +``` + +Create clarification task or add comment to spec. + +### Missing Information + +When critical info is missing: + +```markdown +## Missing Information + +- **[Topic]**: Spec doesn't specify [what's missing] +- **Impact**: Blocks [affected tasks] +- **Action**: Need to [how to resolve] +``` + +### Conflicting Requirements + +When requirements conflict: + +```markdown +## Conflicting Requirements + +**Conflict**: REQ-1 says [X] but REQ-5 says [Y] +**Impact**: [Implementation impact] +**Resolution needed**: [Decision needed] +``` + +## Acceptance Criteria Parsing + +### Explicit Criteria + +Direct acceptance criteria: + +``` +## Acceptance Criteria +- User can log in with email and password +- System sends confirmation email +- Session expires after 24 hours +``` + +Convert to checklist: +- [ ] User can log in with email and password +- [ ] System sends confirmation email +- [ ] Session expires after 24 hours + +### Implicit Criteria + +Derive from requirements: + +``` +Requirement: "Users can upload files up to 100MB" + +Implied acceptance criteria: +- [ ] Files up to 100MB upload successfully +- [ ] Files over 100MB are rejected with error message +- [ ] Progress indicator shows during upload +- [ ] Upload can be cancelled +``` + +### Testable Criteria + +Ensure criteria are testable: + +❌ **Not testable**: "System is fast" +✓ **Testable**: "Page loads in < 2 seconds" + +❌ **Not testable**: "Users like the interface" +✓ **Testable**: "90% of test users complete task successfully" + +## Technical Detail Extraction + +### Architecture Information + +Extract: +- System components +- Data models +- APIs/interfaces +- Integration points +- Technology choices + +### Design Decisions + +Note: +- Technology selections +- Architecture patterns +- Trade-offs made +- Rationale provided + +### Implementation Guidance + +Look for: +- Suggested approach +- Code examples +- Library recommendations +- Best practices mentioned + +## Dependency Identification + +### External Dependencies + +From spec, identify: +- Third-party services required +- External APIs needed +- Infrastructure requirements +- Tool/library dependencies + +### Internal Dependencies + +Identify: +- Other features needed first +- Shared components required +- Team dependencies +- Data dependencies + +### Timeline Dependencies + +Note: +- Hard deadlines +- Milestone dependencies +- Sequencing requirements + +## Scope Extraction + +### In Scope + +What's explicitly included: +- Features to build +- Use cases to support +- Users/personas to serve + +### Out of Scope + +What's explicitly excluded: +- Features deferred +- Use cases not supported +- Edge cases not handled + +### Assumptions + +What's assumed: +- Environment assumptions +- User assumptions +- System state assumptions + +## Risk Identification + +Extract risk information: + +### Technical Risks +- Unproven technology +- Complex integration +- Performance concerns +- Scalability unknowns + +### Business Risks +- Market timing +- Resource availability +- Dependency on others + +### Mitigation Strategies + +Note any mitigation approaches mentioned in spec. + +## Spec Quality Assessment + +Evaluate spec completeness: + +✓ **Good spec**: +- Clear requirements +- Explicit acceptance criteria +- Priorities defined +- Risks identified +- Technical approach outlined + +⚠️ **Incomplete spec**: +- Vague requirements +- Missing acceptance criteria +- Unclear priorities +- No risk analysis +- Technical details absent + +Document gaps and create clarification tasks. + +## Parsing Checklist + +Before creating implementation plan: + +☐ All functional requirements identified +☐ Non-functional requirements noted +☐ Acceptance criteria extracted +☐ Dependencies identified +☐ Risks noted +☐ Ambiguities documented +☐ Technical approach understood +☐ Scope is clear +☐ Priorities are defined + diff --git a/skills/.curated/notion-spec-to-implementation/reference/standard-implementation-plan.md b/skills/.curated/notion-spec-to-implementation/reference/standard-implementation-plan.md new file mode 100644 index 0000000..556a1d0 --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/reference/standard-implementation-plan.md @@ -0,0 +1,146 @@ +# Standard Implementation Plan Template + +Use this template for most feature implementations. + +```markdown +# Implementation Plan: [Feature Name] + +## Overview +[1-2 sentence feature description and business value] + +## Linked Specification +Original Specification + +## Requirements Summary + +### Functional Requirements +- [Requirement 1] +- [Requirement 2] +- [Requirement 3] + +### Non-Functional Requirements +- **Performance**: [Targets] +- **Security**: [Requirements] +- **Scalability**: [Needs] + +### Acceptance Criteria +- [ ] [Criterion 1] +- [ ] [Criterion 2] +- [ ] [Criterion 3] + +## Technical Approach + +### Architecture +[High-level architectural decisions] + +### Technology Stack +- Backend: [Technologies] +- Frontend: [Technologies] +- Infrastructure: [Technologies] + +### Key Design Decisions +1. **[Decision]**: [Rationale] +2. **[Decision]**: [Rationale] + +## Implementation Phases + +### Phase 1: Foundation (Week 1) +**Goal**: Set up core infrastructure + +**Tasks**: +- [ ] Database schema design +- [ ] API scaffolding +- [ ] Authentication setup + +**Deliverables**: Working API skeleton +**Estimated effort**: 3 days + +### Phase 2: Core Features (Week 2-3) +**Goal**: Implement main functionality + +**Tasks**: +- [ ] Feature A implementation +- [ ] Feature B implementation + +**Deliverables**: Core features working +**Estimated effort**: 1 week + +### Phase 3: Integration & Polish (Week 4) +**Goal**: Complete integration and refinement + +**Tasks**: +- [ ] Frontend integration +- [ ] Testing & QA + +**Deliverables**: Production-ready feature +**Estimated effort**: 1 week + +## Dependencies + +### External Dependencies +- [Dependency 1]: [Status] +- [Dependency 2]: [Status] + +### Internal Dependencies +- [Team/component dependency] + +### Blockers +- [Known blocker] or None currently + +## Risks & Mitigation + +### Risk 1: [Description] +- **Probability**: High/Medium/Low +- **Impact**: High/Medium/Low +- **Mitigation**: [Strategy] + +### Risk 2: [Description] +- **Probability**: High/Medium/Low +- **Impact**: High/Medium/Low +- **Mitigation**: [Strategy] + +## Timeline + +| Milestone | Target Date | Status | +|-----------|-------------|--------| +| Phase 1 Complete | [Date] | ⏳ Planned | +| Phase 2 Complete | [Date] | ⏳ Planned | +| Phase 3 Complete | [Date] | ⏳ Planned | +| Launch | [Date] | ⏳ Planned | + +## Success Criteria + +### Technical Success +- [ ] All acceptance criteria met +- [ ] Performance targets achieved +- [ ] Security requirements satisfied +- [ ] Test coverage > 80% + +### Business Success +- [ ] [Business metric 1] +- [ ] [Business metric 2] + +## Resources + +### Documentation +- Design Doc +- API Spec + +### Related Work +- Related Feature + +## Progress Tracking + +[This section updated regularly] + +### Phase Status +- Phase 1: ⏳ Not Started +- Phase 2: ⏳ Not Started +- Phase 3: ⏳ Not Started + +**Overall Progress**: 0% complete + +### Latest Update: [Date] +[Brief status update] +``` + diff --git a/skills/.curated/notion-spec-to-implementation/reference/task-creation-template.md b/skills/.curated/notion-spec-to-implementation/reference/task-creation-template.md new file mode 100644 index 0000000..be0b869 --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/reference/task-creation-template.md @@ -0,0 +1,34 @@ +# Task Creation Template + +When creating tasks from spec. + +```markdown +# [Task Name] + +## Context +Part of implementation for Feature Spec + +Implementation plan: Implementation Plan + +## Description +[What needs to be done] + +## Acceptance Criteria +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +## Technical Details +[Technical approach or notes] + +## Dependencies +- Blocked by: [Task] or None +- Blocks: [Task] or None + +## Resources +- [Link to design] +- [Link to related code] + +## Progress +[To be updated during implementation] +``` + diff --git a/skills/.curated/notion-spec-to-implementation/reference/task-creation.md b/skills/.curated/notion-spec-to-implementation/reference/task-creation.md new file mode 100644 index 0000000..dd74bd6 --- /dev/null +++ b/skills/.curated/notion-spec-to-implementation/reference/task-creation.md @@ -0,0 +1,441 @@ +# Task Creation from Specs + +## Finding the Task Database + +Before creating tasks, locate the task database: + +``` +1. Search for task database: + Notion:notion-search + query: "Tasks" or "Task Management" or "[Project] Tasks" + +2. Fetch database schema: + Notion:notion-fetch + id: "database-id-from-search" + +3. Identify data source: + - Look for tags + - Extract collection ID for parent parameter + +4. Note schema: + - Required properties + - Property types and options + - Relation properties for linking + +Example: +Notion:notion-search +query: "Engineering Tasks" +query_type: "internal" + +Notion:notion-fetch +id: "tasks-database-id" +``` + +Result: `collection://abc-123-def` for use as parent + +## Task Breakdown Strategy + +### Size Guidelines + +**Good task size**: +- Completable in 1-2 days +- Single clear deliverable +- Independently testable +- Minimal dependencies + +**Too large**: +- Takes > 3 days +- Multiple deliverables +- Many dependencies +- Break down further + +**Too small**: +- Takes < 2 hours +- Too granular +- Group with related work + +### Granularity by Phase + +**Early phases**: Larger tasks acceptable +- "Design database schema" +- "Set up API structure" + +**Middle phases**: Medium-sized tasks +- "Implement user authentication" +- "Build dashboard UI" + +**Late phases**: Smaller, precise tasks +- "Fix validation bug in form" +- "Add loading state to button" + +## Task Creation Pattern + +For each requirement or work item: + +``` +1. Identify the work +2. Determine task size +3. Create task in database +4. Set properties +5. Write task description +6. Link to spec/plan +``` + +### Creating Task + +``` +Use Notion:notion-create-pages: + +parent: { + type: "data_source_id", + data_source_id: "collection://tasks-db-uuid" +} + +properties: { + "[Title Property]": "Task: [Clear task name]", + "Status": "To Do", + "Priority": "[High/Medium/Low]", + "[Project/Related]": ["spec-page-id", "plan-page-id"], + "Assignee": "[Person]" (if known), + "date:Due Date:start": "[Date]" (if applicable), + "date:Due Date:is_datetime": 0 +} + +content: "[Task description using template]" +``` + +## Task Description Template + +```markdown +# [Task Name] + +## Context +Implementation task for Feature Spec + +Part of Implementation Plan - Phase [N] + +## Objective +[What this task accomplishes] + +## Requirements +Based on spec requirements: +- [Relevant requirement 1] +- [Relevant requirement 2] + +## Acceptance Criteria +- [ ] [Specific, testable criterion] +- [ ] [Specific, testable criterion] +- [ ] [Specific, testable criterion] + +## Technical Approach +[Suggested implementation approach] + +### Components Affected +- [Component 1] +- [Component 2] + +### Key Decisions +- [Decision point 1] +- [Decision point 2] + +## Dependencies + +### Blocked By +- Prerequisite Task or None + +### Blocks +- Dependent Task or None + +## Resources +- [Link to design mockup] +- [Link to API spec] +- [Link to relevant code] + +## Estimated Effort +[Time estimate] + +## Progress +[To be updated during implementation] +``` + +## Task Types + +### Infrastructure/Setup Tasks + +``` +Title: "Setup: [What's being set up]" +Examples: +- "Setup: Configure database connection pool" +- "Setup: Initialize authentication middleware" +- "Setup: Create CI/CD pipeline" + +Focus: Getting environment/tooling ready +``` + +### Feature Implementation Tasks + +``` +Title: "Implement: [Feature name]" +Examples: +- "Implement: User login flow" +- "Implement: File upload functionality" +- "Implement: Dashboard widget" + +Focus: Building specific functionality +``` + +### Integration Tasks + +``` +Title: "Integrate: [What's being integrated]" +Examples: +- "Integrate: Connect frontend to API" +- "Integrate: Add payment provider" +- "Integrate: Link user profile to dashboard" + +Focus: Connecting components +``` + +### Testing Tasks + +``` +Title: "Test: [What's being tested]" +Examples: +- "Test: Write unit tests for auth service" +- "Test: E2E testing for checkout flow" +- "Test: Performance testing for API" + +Focus: Validation and quality assurance +``` + +### Documentation Tasks + +``` +Title: "Document: [What's being documented]" +Examples: +- "Document: API endpoints" +- "Document: Setup instructions" +- "Document: Architecture decisions" + +Focus: Creating documentation +``` + +### Bug Fix Tasks + +``` +Title: "Fix: [Bug description]" +Examples: +- "Fix: Login error on Safari" +- "Fix: Memory leak in image processing" +- "Fix: Race condition in payment flow" + +Focus: Resolving issues +``` + +### Refactoring Tasks + +``` +Title: "Refactor: [What's being refactored]" +Examples: +- "Refactor: Extract auth logic to service" +- "Refactor: Optimize database queries" +- "Refactor: Simplify component hierarchy" + +Focus: Code quality improvement +``` + +## Sequencing Tasks + +### Critical Path + +Identify must-happen-first tasks: + +``` +1. Database schema +2. API foundation +3. Core business logic +4. Frontend integration +5. Testing +6. Deployment +``` + +### Parallel Tracks + +Tasks that can happen simultaneously: + +``` +Track A: Backend development +- API endpoints +- Business logic +- Database operations + +Track B: Frontend development +- UI components +- State management +- Routing + +Track C: Infrastructure +- CI/CD setup +- Monitoring +- Documentation +``` + +### Phase-Based Sequencing + +Group by implementation phase: + +``` +Phase 1 (Foundation): +- Setup tasks +- Infrastructure tasks + +Phase 2 (Core): +- Feature implementation tasks +- Integration tasks + +Phase 3 (Polish): +- Testing tasks +- Documentation tasks +- Optimization tasks +``` + +## Priority Assignment + +### P0/Critical +- Blocks everything else +- Core functionality +- Security requirements +- Data integrity + +### P1/High +- Important features +- User-facing functionality +- Performance requirements + +### P2/Medium +- Nice-to-have features +- Optimizations +- Minor improvements + +### P3/Low +- Future enhancements +- Edge case handling +- Cosmetic improvements + +## Estimation + +### Story Points + +If using story points: +- 1 point: Few hours +- 2 points: Half day +- 3 points: Full day +- 5 points: 2 days +- 8 points: 3-4 days (consider breaking down) + +### Time Estimates + +Direct time estimates: +- 2-4 hours: Small task +- 1 day: Medium task +- 2 days: Large task +- 3+ days: Break down further + +### Estimation Factors + +Consider: +- Complexity +- Unknowns +- Dependencies +- Testing requirements +- Documentation needs + +## Task Relationships + +### Parent Task Pattern + +For large features: + +``` +Parent: "Feature: User Authentication" +Children: +- "Setup: Configure auth library" +- "Implement: Login flow" +- "Implement: Password reset" +- "Test: Auth functionality" +``` + +### Dependency Chain Pattern + +For sequential work: + +``` +Task A: "Design database schema" +↓ (blocks) +Task B: "Implement data models" +↓ (blocks) +Task C: "Create API endpoints" +↓ (blocks) +Task D: "Integrate with frontend" +``` + +### Related Tasks Pattern + +For parallel work: + +``` +Central: "Feature: Dashboard" +Related: +- "Backend API for dashboard data" +- "Frontend dashboard component" +- "Dashboard data caching" +``` + +## Bulk Task Creation + +When creating many tasks: + +``` +For each work item in breakdown: + 1. Determine task properties + 2. Create task page + 3. Link to spec/plan + 4. Set relationships + +Then: + 1. Update plan with task links + 2. Review sequencing + 3. Assign tasks (if known) +``` + +## Task Naming Conventions + +**Be specific**: +✓ "Implement user login with email/password" +✗ "Add login" + +**Include context**: +✓ "Dashboard: Add revenue chart widget" +✗ "Add chart" + +**Use action verbs**: +- Implement, Build, Create +- Integrate, Connect, Link +- Fix, Resolve, Debug +- Test, Validate, Verify +- Document, Write, Update +- Refactor, Optimize, Improve + +## Validation Checklist + +Before finalizing tasks: + +☐ Each task has clear objective +☐ Acceptance criteria are testable +☐ Dependencies identified +☐ Appropriate size (1-2 days) +☐ Priority assigned +☐ Linked to spec/plan +☐ Proper sequencing +☐ Resources noted +