Notion Knowledge Capture

Knowledge Capture

Transforms conversations, discussions, and insights into structured documentation in your Notion workspace. Captures knowledge from chat context, formats it appropriately, and saves it to the right location with proper organization and linking.

Quick Start

When asked to save information to Notion:

1. Extract content: Identify key information from conversation context 2. Structure information: Organize into appropriate documentation format 3. Determine location: Use Notion:notion-search to find appropriate wiki page/database 4. Create page: Use Notion:notion-create-pages to save content 5. Make discoverable: Link from relevant hub pages, add to databases, or update wiki navigation so others can find it

Knowledge Capture Workflow

Step 1: Identify content to capture

From conversation context, extract:
- Key concepts and definitions
- Decisions made and rationale
- How-to information and procedures
- Important insights or learnings
- Q&A pairs
- Examples and use cases

Step 2: Determine content type

Classify the knowledge:
- Concept/Definition
- How-to Guide
- Decision Record
- FAQ Entry
- Meeting Summary
- Learning/Post-mortem
- Reference Documentation

Step 3: Structure the content

Format appropriately based on content type:
- Use templates for consistency
- Add clear headings and sections
- Include examples where helpful
- Add relevant metadata
- Link to related pages

Step 4: Determine destination

Where to save:
- Wiki page (general knowledge base)
- Specific project page (project-specific knowledge)
- Documentation database (structured docs)
- FAQ database (questions and answers)
- Decision log (architecture/product decisions)
- Team wiki (team-specific knowledge)

Step 5: Create the page

Use Notion:notion-create-pages:
- Set appropriate title
- Use structured content from template
- Set properties if in database
- Add tags/categories
- Link to related pages

Step 6: Make content discoverable

Link the new page so others can find it:

1. Update hub/index pages:
   - Add link to wiki table of contents page
   - Add link from relevant project page
   - Add link from category/topic page (e.g., "Engineering Docs")

2. If page is in a database:
   - Set appropriate tags/categories
   - Set status (e.g., "Published")
   - Add to relevant views

3. Optionally update parent page:
   - If saved under a project, add to project's "Documentation" section
   - If in team wiki, ensure it's linked from team homepage

Example:
Notion:notion-update-page
page_id: "team-wiki-homepage-id"
command: "insert_content_after"
selection_with_ellipsis: "## How-To Guides..."
new_str: "- <mention-page url='...'>How to Deploy to Production</mention-page>"

This step ensures the knowledge doesn't become "orphaned" - it's properly connected to your workspace's navigation structure.

Content Types

Choose appropriate structure based on content:

Concept: Overview → Definition → Characteristics → Examples → Use Cases → Related How-To: Overview → Prerequisites → Steps (numbered) → Verification → Troubleshooting → Related Decision: Context → Decision → Rationale → Options Considered → Consequences → Implementation FAQ: Short Answer → Detailed Explanation → Examples → When to Use → Related Questions Learning: What Happened → What Went Well → What Didn't → Root Causes → Learnings → Actions

Destination Patterns

General Wiki: Standalone page → add to index → tag → link from related pages

Project Wiki: Child of project page → link from project overview → tag with project name

Documentation Database: Use properties (Title, Type, Category, Tags, Last Updated, Owner)

Decision Log Database: Use properties (Decision, Date, Status, Domain, Deciders, Impact)

FAQ Database: Use properties (Question, Category, Tags, Last Reviewed, Useful Count)

See reference/database-best-practices.md for database selection guide and individual schema files.

Content Extraction from Conversations

Chat Discussion: Key points, conclusions, resources, action items, Q&A

Problem-Solving: Problem statement, approaches tried, solution, why it worked, future considerations

Knowledge Sharing: Concept explained, examples, best practices, common pitfalls, resources

Decision Discussion: Question, options, trade-offs, decision, rationale, next steps

Formatting Best Practices

Structure: Use # (title), ## (sections), ### (subsections) consistently

Writing: Start with overview, use bullets, keep paragraphs short, add examples

Linking: Link related pages, mention people, reference resources, create bidirectional links

Metadata: Include date, author, tags, status

Searchability: Clear titles, natural keywords, common search tags, image alt-text

Indexing and Organization

Wiki Index: Organize by sections (Getting Started, How-To Guides, Reference, FAQs, Decisions) with page links

Category Pages: Create landing pages with overview, doc links, and recent updates

Tagging Strategy: Use consistent tags for technology/tools, topics, audience, and status

Update Management

Create New: Content is substantive (>2 paragraphs), will be referenced multiple times, part of knowledge base, needs independent discovery

Update Existing: Adding to existing topic, correcting info, expanding concept, updating for changes

Versioning: Add update history section for significant changes (date, author, what changed, why)

Best Practices

1. Capture promptly: Document while context is fresh 2. Structure consistently: Use templates for similar content 3. Link extensively: Connect related knowledge 4. Write for discovery: Use searchable titles and tags 5. Include context: Why this matters, when to use 6. Add examples: Concrete examples aid understanding 7. Maintain: Review and update periodically 8. Get feedback: Ask if documentation is helpful

Advanced Features

Documentation databases: See reference/database-best-practices.md for database schema patterns.

Common Issues

"Not sure where to save": Default to general wiki, can move later "Content is fragmentary": Group related fragments into cohesive doc "Already exists": Search first, update existing if appropriate "Too informal": Clean up language while preserving insights

Examples

See examples/ for complete workflows:

• examples/conversation-to-faq.md - FAQ from Q&A
• examples/decision-capture.md - Decision record
• examples/how-to-guide.md - How-to from discussion

Knowledge Capture Skill Evaluations

Evaluation scenarios for testing the Knowledge Capture skill across different Claude 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"

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\nCommon 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\nCommon 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\nAlways 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

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

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

   git checkout main && git pull

````

1. Tag release

   git tag -a v1.2.3 -m "Release v1.2.3"
   git push origin v1.2.3

1. Trigger deployment

• GitHub Actions auto-starts from tag push
• Monitor: https://github.com/org/repo/actions

1. Database migrations (if needed)

• Auto-run in GitHub Actions
• Check logs for completion

1. 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)

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:

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

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

Decision Log Database (ADR - Architecture Decision Records)

Purpose: Track important decisions with context and rationale.

Schema

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

General Documentation Database

Purpose: Store all types of documentation in a searchable, organized database.

Schema

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

FAQ Database

Purpose: Organize frequently asked questions with answers.

Schema

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

How-To Guide Database

Purpose: Procedural documentation for common tasks.

Schema

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

Learning/Post-Mortem Database

Purpose: Capture learnings from incidents, projects, or experiences.

Schema

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

Team Wiki Database

Purpose: Centralized team knowledge and resources.

Schema

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