What it does. Capture conversations and decisions into structured Notion pages; use when turning chats/notes into wiki entries, how-tos, decisions, or FAQs with proper linking. Part of openai/skills (Skills Catalog for Codex) (openai/skills).

Upstream	openai/skills
Skill file	skills/.curated/notion-knowledge-capture/SKILL.md
License	MIT (skill folder LICENSE.txt)
Author	OpenAI
Fetched	2026-09-10

Install

• Codex: $skill-installer installs from this catalog ($notion-knowledge-capture invokes it); other agents: npx skills add openai/skills --skill notion-knowledge-capture.
• Raw file: curl -sL https://raw.githubusercontent.com/openai/skills/HEAD/skills/.curated/notion-knowledge-capture/SKILL.md

SKILL.md (verbatim)

name: notion-knowledge-capture
description: Capture conversations and decisions into structured Notion pages; use when turning chats/notes into wiki entries, how-tos, decisions, or FAQs with proper linking.
metadata:
  short-description: Capture conversations into structured Notion pages

Knowledge Capture

Convert conversations and notes into structured, linkable Notion pages for easy reuse.

Quick start

1. Clarify what to capture (decision, how-to, FAQ, learning, documentation) and target audience.
2. Identify the right database/template in reference/ (team wiki, how-to, FAQ, decision log, learning, documentation).
3. Pull any prior context from Notion with Notion:notion-search → Notion:notion-fetch (existing pages to update/link).
4. Draft the page with Notion:notion-create-pages using the database’s schema; include summary, context, source links, and tags/owners.
5. Link from hub pages and related records; update status/owners with Notion:notion-update-page as the source evolves.

Workflow

0) If any MCP call fails because Notion MCP is not connected, pause and set it up:

1. Add the Notion MCP:
   • codex mcp add notion --url https://mcp.notion.com/mcp
2. Enable remote MCP client:
   • Set [features].rmcp_client = true in config.toml or run codex --enable rmcp_client
3. Log in with OAuth:
   • codex mcp login notion

After successful login, the user will have to restart codex. You should finish your answer and tell them so when they try again they can continue with Step 1.

1) Define the capture

• Ask purpose, audience, freshness, and whether this is new or an update.
• Determine content type: decision, how-to, FAQ, concept/wiki entry, learning/note, documentation page.

2) Locate destination

• Pick the correct database using reference/*-database.md guides; confirm required properties (title, tags, owner, status, date, relations).
• If multiple candidate databases, ask the user which to use; otherwise, create in the primary wiki/documentation DB.

3) Extract and structure

• Extract facts, decisions, actions, and rationale from the conversation.
• For decisions, record alternatives, rationale, and outcomes.
• For how-tos/docs, capture steps, pre-reqs, links to assets/code, and edge cases.
• For FAQs, phrase as Q&A with concise answers and links to deeper docs.

4) Create/update in Notion

• Use Notion:notion-create-pages with the correct data_source_id; set properties (title, tags, owner, status, dates, relations).
• Use templates in reference/ to structure content (section headers, checklists).
• If updating an existing page, fetch then edit via Notion:notion-update-page.

5) Link and surface

• Add relations/backlinks to hub pages, related specs/docs, and teams.
• Add a short summary/changelog for future readers.
• If follow-up tasks exist, create tasks in the relevant database and link them.

References and examples

• reference/ — database schemas and templates (e.g., team-wiki-database.md, how-to-guide-database.md, faq-database.md, decision-log-database.md, documentation-database.md, learning-database.md, database-best-practices.md).
• examples/ — capture patterns in practice (e.g., decision-capture.md, how-to-guide.md, conversation-to-faq.md).

Other files in this skill

• LICENSE.txt
• agents/openai.yaml
• assets/notion-small.svg
• assets/notion.png
• evaluations/README.md
• evaluations/conversation-to-wiki.json
• evaluations/decision-record.json
• examples/conversation-to-faq.md
• examples/decision-capture.md
• examples/how-to-guide.md
• reference/database-best-practices.md
• reference/decision-log-database.md
• reference/documentation-database.md
• reference/faq-database.md
• reference/how-to-guide-database.md
• reference/learning-database.md
• reference/team-wiki-database.md

evaluations/README.md (verbatim)

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"

examples/conversation-to-faq.md (verbatim)

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 <PID>\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- <mention-page url=\"...\">How do I check what's using a port?</mention-page>\n- <mention-page url=\"...\">How do I configure the application port?</mention-page>\n- <mention-page url=\"...\">PM2 deployment best practices</mention-page>\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- <mention-page url=\"...\">How do I configure database connection pooling?</mention-page>\n- <mention-page url=\"...\">Database backup and restore procedures</mention-page>\n- <mention-page url=\"...\">Database performance optimization</mention-page>\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- <mention-page url=\"...\">How do I set up log aggregation?</mention-page>\n- <mention-page url=\"...\">Deployment checklist and best practices</mention-page>\n- <mention-page url=\"...\">How to roll back a failed deployment?</mention-page>\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: "
- <mention-page url=\"...\">Why does deployment fail with 'port already in use' error?</mention-page>
- <mention-page url=\"...\">Why do I get 'cannot connect to database' errors?</mention-page>
- <mention-page url=\"...\">What's the first thing I should check when deployment fails?</mention-page>
"

Summary Provided to User

## 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: <mention-page url="...">Port already in use FAQ</mention-page>

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: <mention-page url="...">Database connection FAQ</mention-page>

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: <mention-page url="...">Troubleshooting first steps FAQ</mention-page>

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

examples/decision-capture.md (verbatim)

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:

# 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

examples/how-to-guide.md (verbatim)

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

# 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

   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

• <mention-page url="...">Rollback Procedure</mention-page>
• <mention-page url="...">Database Migration Guide</mention-page>

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

## reference/database-best-practices.md (verbatim)

# 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
Track decisions	Decision Log
Q&A knowledge base	FAQ Database
Team-specific content	Team Wiki
Step-by-step guides	How-To Guide Database
Incident/project learnings	Learning Database

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

reference/decision-log-database.md (verbatim)

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

reference/documentation-database.md (verbatim)

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:

{
  "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

reference/faq-database.md (verbatim)

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

reference/how-to-guide-database.md (verbatim)

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

reference/learning-database.md (verbatim)

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

reference/team-wiki-database.md (verbatim)

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

Back to openai/skills (Skills Catalog for Codex) or Agent skills.