notion-sync

Notion Sync Skill

Standardize how Notion tasks are updated across all modes.

When to Use

• Push PR mode: update PR link and append plan
• Init mode: update branch name
• Any mode updating task status
• Appending content to task pages

Phases

Phase 1: Retrieve Task Page

Fetch current task state:

API-retrieve-a-page:
  page_id: [task-page-id]

Verify the page exists and note current field values.

Phase 2: Update Standard Fields

Update properties based on context:

Available fields:

| Field | Type | When to Update | |-------|------|----------------| | Github PR link | url | On PR creation | | Branch name | rich_text | On branch creation | | Lifecycle/Status | select | On state changes |

API call:

API-patch-page:
  page_id: [task-page-id]
  properties:
    "Github PR link": { url: "[PR-URL]" }
    "Branch name": { rich_text: [{ text: { content: "[branch-name]" }}]}

Phase 3: Append Content (Optional)

If content needs to be added to the page body:

Get existing blocks:

API-get-block-children:
  block_id: [page-id]

Append new content:

API-patch-block-children:
  block_id: [page-id]
  children: [
    {
      "type": "heading_2",
      "heading_2": { "rich_text": [{ "text": { "content": "Implementation Plan" }}]}
    },
    {
      "type": "paragraph",
      "paragraph": { "rich_text": [{ "text": { "content": "[plan-content]" }}]}
    }
  ]

Content types to append:

• Implementation plans (from Plan mode)
• PR summaries (from Push PR mode)
• Status updates

Phase 4: Confirm Sync

Verify the update was successful:

API-retrieve-a-page:
  page_id: [task-page-id]

Check that updated fields reflect new values.

Phase 5: Session Journal Sync (NEW)

Sync session metrics and decisions to Session Journal database.

When to Run

• After PR is created (via push-pr.mdc)
• On manual "sync session" command
• On session abandon

5.1: Gather Session Data

Collect from session-status skill:

• Duration, loops, rework, waiting, RED count, escalations

Collect from decision-capture skill:

• Decisions made this session (KO, significant OK)
• Learnings captured (Kaizen/Hansei)

5.2: Check for Existing Session

Notion MCP: API-post-search
  query: "[branch-name]"
  filter:
    property: "object"
    value: "page"
  sort:
    property: "last_edited_time"
    direction: "descending"

5.3: Create or Update Session Page

If new session:

Notion MCP: API-post-page
  parent: { database_id: "[SESSION_JOURNAL_DB_ID]" }
  properties:
    Title: { title: [{ text: { content: "[Feature] - [Date]" }}]}
    Task: { relation: [{ id: "[kanban_task_id]" }]}
    Date: { date: { start: "[session_date]" }}
    Duration: { number: [total_minutes] }
    Phase Reached: { select: { name: "[phase]" }}
    Outcome: { select: { name: "[outcome]" }}
    Loops: { number: [total_loops] }
    Rework: { number: [rework_count] }
    Waiting: { number: [waiting_minutes] }
    RED Count: { number: [red_count] }
    Escalations: { number: [escalation_count] }
    Branch: { rich_text: [{ text: { content: "[branch-name]" }}]}

If existing session:

Notion MCP: API-patch-page
  page_id: [existing_page_id]
  properties:
    Duration: { number: [updated_minutes] }
    Phase Reached: { select: { name: "[latest_phase]" }}
    Outcome: { select: { name: "[outcome]" }}
    Loops: { number: [updated_loops] }
    ... (other updated metrics)

5.4: Append Decisions and Learnings

Notion MCP: API-patch-block-children
  block_id: [session_page_id]
  children:
    - type: heading_2
      heading_2: { rich_text: [{ text: { content: "Decisions" }}]}
    - type: bulleted_list_item
      bulleted_list_item: { rich_text: [{ text: { content: "[KO] [decision 1] - [rationale]" }}]}
    - type: bulleted_list_item
      bulleted_list_item: { rich_text: [{ text: { content: "[OK] [decision 2] - [rationale]" }}]}
    - type: heading_2
      heading_2: { rich_text: [{ text: { content: "Learnings" }}]}
    - type: bulleted_list_item
      bulleted_list_item: { rich_text: [{ text: { content: "[Kaizen] [learning 1]" }}]}
    - type: bulleted_list_item
      bulleted_list_item: { rich_text: [{ text: { content: "[Hansei] [learning 2]" }}]}

5.5: Link to Kanban Task

Notion MCP: API-patch-page
  page_id: [kanban_task_id]
  properties:
    Session Journal: { relation: [{ id: "[session_page_id]" }]}

5.6: Create ADR for High-Impact Decisions

If any decision has Impact = HIGH:

1. Create ADR file in /docs/decisions/
2. Link ADR URL in Session Journal page

Session Journal Output

## Session Journal Synced

**Session:** [Feature] - [Date]
**Page:** [Notion URL]
**Kanban:** Linked to [Task name]

### Metrics Recorded
- Duration: [N]min
- Loops: [N]
- Rework: [N]
- RED Count: [N]
- Escalations: [N]

### Decisions: [N] captured
### Learnings: [N] captured
[If ADR: ADR-[NNN] created]

**Status:** Sync successful

Output

Present sync summary:

## Notion Sync Complete

**Task:** [task-title]
**Page ID:** [page-id]

### Updates Applied
- ✅ Github PR link: [url]
- ✅ Branch name: [branch]
- ✅ Content appended: [description]

**Status:** Sync successful

Standard Field Reference

Staffing Database ID: 256c4d5e-7bea-80ca-ba8d-c0ba0bb881c6

Common Properties:

• Github PR link (url) - Link to GitHub PR
• Branch name (rich_text) - Git branch name
• Lifecycle or Status (select) - Task state
• Assignee (people) - Task owner
• Sprint (relation) - Sprint association

Integration

This skill is invoked by:

• push-pr.mdc - Phase 2.2 (Sync Notion) + Phase 4 (Session Journal)
• init.mdc - Update branch name
• Any mode needing Notion updates
• Manual "sync session" command

Notion MCP Tools:

• API-retrieve-a-page - Get task details
• API-get-block-children - Get page content
• API-patch-page - Update page properties
• API-patch-block-children - Add content to page
• API-post-page - Create new session entries
• API-post-search - Find existing sessions by branch