Notion Brief Publishing Skill

Overview

This skill handles publishing approved product briefs from the briefs/ folder to Notion with the correct structure, including inline databases for User Scenarios and Deliverables Tracker.

When to Use This Skill

Use this skill when:

• •User explicitly requests to publish a brief to Notion (e.g., "publish to Notion", "create this in Notion")
• •A brief in briefs/ folder has been approved and needs to be added to the Projects database

Prerequisites

Before publishing, ensure:

1. •Brief exists in briefs/ folder as markdown
2. •Brief content has been approved by user
3. •User has confirmed:
   • •Team assignment (which team will own this work)
   • •Product classification (which product this feature belongs to)

CRITICAL: Always ask for Team and Product before publishing. Do NOT proceed without this information.

Configuration

Read database IDs and team/product references from .claude/config/organization.json:

• •integrations.notion.projects_database_id - Target database for briefs
• •integrations.notion.template_id - Template page ID
• •teams - Available teams
• •products - Available products

Step-by-Step Publishing Workflow

Step 1: Ask for Required Information

Before any Notion operations, ask the user:

Before I publish this brief to Notion, I need to confirm:
1. Which team will own this work?
2. Which product(s) does this feature fall under?

Step 2: Create Page in Projects Database

Use notion-create-pages with:
  parent: {"type": "data_source_id", "data_source_id": "[projects_database_id from config]"}
  pages: [{
    "properties": {
      "Project Brief": "[Brief Title]",
      "Status": "Not Started"
    },
    "content": "[Brief content in Notion markdown format]"
  }]

Step 3: Set Team and Product Relations

Use notion-update-page with command: "update_properties"
Set Team(s) and Products relations using the page URLs

Step 4: Create User Scenarios Inline Database

CRITICAL: The Notion API cannot create inline databases directly. You must:

1. •Create the database as a child of the brief page:

Use notion-create-database with:
  parent: {"type": "page_id", "page_id": "[brief page ID]"}
  title: [{"type": "text", "text": {"content": "User Scenarios"}}]
  properties: {
    "Name": {"type": "title", "title": {}},
    "Scope": {
      "type": "select",
      "select": {
        "options": [
          {"name": "In Scope", "color": "green"},
          {"name": "Out of Scope", "color": "red"}
        ]
      }
    }
  }

1. •Set database to inline display:

Use notion-update-database with:
  database_id: "[database ID]"
  is_inline: true

1. •Add scenarios to the database:

Use notion-create-pages with:
  parent: {"type": "data_source_id", "data_source_id": "[User Scenarios collection URL]"}
  pages: [
    {
      "properties": {"Name": "Scenario title", "Scope": "In Scope"},
      "content": "[Full scenario content]"
    }
  ]

Step 5: Create Deliverables Tracker Inline Database

1. •Create the database:

Use notion-create-database with:
  parent: {"type": "page_id", "page_id": "[brief page ID]"}
  title: [{"type": "text", "text": {"content": "Deliverables tracker"}}]
  properties: {
    "Deliverable": {"type": "title", "title": {}},
    "Status": {
      "type": "select",
      "select": {
        "options": [
          {"name": "Not started", "color": "default"},
          {"name": "In progress", "color": "blue"},
          {"name": "Not needed", "color": "green"},
          {"name": "Delivered", "color": "green"}
        ]
      }
    },
    "Date": {"type": "date", "date": {}}
  }

NOTE: The Notion API does not support creating status type properties. Use select type instead with the same options.

1. •Set database to inline display:

Use notion-update-database with:
  database_id: "[database ID]"
  is_inline: true

1. •Add standard deliverables:

Use notion-create-pages with:
  parent: {"type": "data_source_id", "data_source_id": "[Deliverables Tracker collection URL]"}
  pages: [
    {"properties": {"Deliverable": "RFC's", "Status": "Not started"}},
    {"properties": {"Deliverable": "Lo-fi Designs", "Status": "Not started"}},
    {"properties": {"Deliverable": "Hi-fi Designs", "Status": "Not started"}},
    {"properties": {"Deliverable": "User Scenarios", "Status": "Delivered"}},
    {"properties": {"Deliverable": "SWAG", "Status": "Not started"}}
  ]

Step 6: Reposition Databases to Correct Sections

CRITICAL: When databases are created as children of a page, Notion appends them to the bottom of the page content. You MUST reposition them to their correct sections.

After creating both databases and adding their content, use notion-update-page with command: "replace_content" to replace the ENTIRE page content with the databases embedded in their correct locations:

1. •User Scenarios database must appear directly under the ## User Scenarios header
2. •Deliverables tracker database must appear under the ## Notes section, before ## Resource Links

Database reference format:

<database url="https://www.notion.so/[db-id]" inline="true" data-source-url="collection://[data-source-id]">Database Name</database>

Standard Deliverables

Always create these rows in the Deliverables Tracker:

Valid Status values: "Not started", "In progress", "Not needed", "Delivered"

User Scenarios Database Schema

• •Name (title): Scenario name using verb + noun format
• •Scope (select): "In Scope" (green) or "Out of Scope" (red)

Each scenario page should contain the full scenario content following the template format.

Required Page Properties

When creating/updating the brief page, set these properties:

• •Project Brief (title): The brief name
• •Status: One of "Not Started", "In Discovery", "In Development", "In UAT", "Ready for Launch", "Done"
• •Team(s): Relation to team page
• •Products: Relation to product page
• •Epic: URL to epic (if available)

Troubleshooting

Database Not Showing as Inline

If the database appears as a child page instead of inline:

1. •Use notion-update-database with is_inline: true
2. •Verify by fetching the page and checking inline="true" in the database tag

Status Property Issues

The Notion API does not support creating status type properties via API. Use select type instead with the same options. The visual difference is minimal.

Database Reference Not Working

Ensure database references use the correct format without double braces:

<database url="https://www.notion.so/[id]" inline="true" data-source-url="collection://[id]">Name</database>

Content Replacement Issues

Use replace_content_range with unique selection snippets. If multiple matches exist, use replace_content to replace entire content (but be careful to preserve database blocks).

Key Reminders

1. •Always ask for Team and Product first - Never assume
2. •Use select instead of status - API limitation
3. •Set is_inline: true - Databases default to child pages
4. •Add standard deliverables - 5 standard rows every time
5. •User Scenarios need Scope property - In Scope/Out of Scope with colors
6. •ALWAYS reposition databases - Notion appends databases to bottom; you must use replace_content to move them to their correct sections