Notion Evidence-First Advanced Troubleshooting

Overview

Diagnose difficult Notion integration failures from redacted evidence without trial-and-error writes.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Treat the HTTP status, Notion error code, request identifier, selected API version, object type, and connection access graph as separate evidence. A page, database, and data source ID are not interchangeable. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Use a redacted credential fingerprint only. Confirm connection type, token owner, capabilities, shared content, and environment; never copy a bearer token into a bundle.

Instructions

1. Freeze retries and preserve one representative response with its request identifier.
2. Reconstruct the request method, object type, selected version, payload shape, and target environment.
3. Trace effective access from token owner through capabilities and explicitly shared content.
4. Classify the fault as transport, authentication, authorization, object identity, version shape, limit, conflict, or service failure.
5. Reproduce with a read-only metadata request or fixture before proposing any write.
6. Return the smallest corrective change, rollback, and escalation evidence.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require the content owner before reading a new page, expanding capabilities, changing sharing, replaying a write, or sending evidence to support.

Error Handling

• Do not convert a 403 into a broader token request until content sharing and capabilities are independently checked.
• Do not retry validation or conflict errors blindly.
• If evidence contains secrets or workspace content, stop and redact before continuing.

Output

Return a timeline, request fingerprint, evidence table, fault classification, ruled-out causes, minimal fix, rollback, and escalation package. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Separate an inaccessible data source from a malforme…

Notion Integration Architecture Decision

Overview

Choose a Notion integration architecture from explicit consistency, latency, security, and recovery requirements.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Notion exposes versioned REST resources, paginated reads, connection webhooks, and mutable limits. Architecture must tolerate additive response fields, out-of-order signals, partial pagination, and changing quotas. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Map each component to a distinct connection or token boundary. Keep inbound webhook verification material, Notion access, queue administration, and destination credentials separated.

Instructions

1. State the business operation, source of truth, consistency objective, recovery point, and recovery time.
2. Inventory reads, writes, webhook signals, scheduled reconciliation, files, and downstream processors.
3. Compare direct request, queued worker, scheduled batch, and webhook-plus-reconciliation variants.
4. Model pagination, retry, idempotency, backpressure, dead letters, and replay for each candidate.
5. Threat-model credentials, workspace content, tenant isolation, logs, and operator privileges.
6. Choose one variant with rejected alternatives, capacity assumptions, rollout gates, and rollback.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require security and data-owner approval for new connections, external processors, production queues, workspace-wide access, or cross-tenant data movement.

Error Handling

• A webhook is a change signal, not a complete or ordered event log.
• Do not multiply tokens to evade connection limits.
• Reject a design without reconciliation and replay boundaries.

Output

Return a decision record, context diagram, trust boundaries, capacity model, failure modes, rollout stages, and rollback triggers. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Choose webhook plus reconciliation for freshness without treating delivery as …

Notion Contract-Safe CI Integration

Overview

Build CI checks for Notion integration contracts without exposing tokens or mutating production content.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

CI should validate local contracts by default. Any live smoke test needs a dedicated non-production connection, explicitly shared fixture content, bounded reads, and a pinned tested API version. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Use short-lived CI secret delivery where supported and a least-privilege non-production token. Mask values and prevent fork jobs from receiving secrets.

Instructions

1. Define offline unit, schema, pagination, error, webhook-signature, and migration fixtures.
2. Pin the SDK and tested API version in the dependency and contract matrix.
3. Separate secret-free pull-request jobs from trusted-branch live smoke tests.
4. Make the live lane read-only, fixture-scoped, time-bounded, and concurrency-limited.
5. Capture redacted status, error code, and request identifier without response content.
6. Gate promotion on exact fixtures, negative paths, rollback evidence, and named ownership.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require repository-admin and workspace-owner approval before enabling secrets, live reads, writes, scheduled jobs, or third-party CI access.

Error Handling

• Fork pull requests must never receive Notion credentials.
• A skipped trusted live job is not a pass; report it distinctly.
• Do not auto-update snapshots from live production responses.

Output

Return the CI trust matrix, job definitions, fixture inventory, secret provenance, gate results, and remediation owner. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Reject a pull request that reintroduces an old object shape.
• Run a read-only bot-identity probe only on a protected trusted branch.

Validation

Exercise and record these paths with expected and observed results:

• …

Notion Error Classification and Recovery

Overview

Classify Notion API failures and choose a bounded recovery path from the observed status and error code.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

The response status, structured code, message, request identifier, and Retry-After header are evidence. Recovery differs for invalid credentials, restricted resources, wrong IDs, invalid payloads, conflicts, rate limits, and service faults. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Verify token presence through a fingerprint or secret-manager reference. Check connection capabilities and content sharing separately from identity.

Instructions

1. Capture one redacted response envelope and the originating operation.
2. Map the status and structured code to authentication, authorization, validation, identity, concurrency, limit, or service class.
3. Check selected API version and page/database/data-source identity before changing code.
4. Apply the class-specific action: correct input, restore access, wait as instructed, reconcile conflict, or pause for service recovery.
5. Retry only retryable classes with a strict attempt and time budget.
6. Verify recovery with the least-privilege read or fixture that proves the original fault is gone.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require approval before capability changes, content sharing, token rotation, write replay, bulk retry, or support disclosure.

Error Handling

• Do not treat every 404 as absence; inaccessible content can be indistinguishable from a bad identifier.
• Respect Retry-After instead of a fixed sleep.
• Quarantine unknown codes rather than guessing.

Output

Return the observed evidence, class, likely causes, ruled-out causes, recovery action, retry budget, and verification result. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Differentiate a wrong data-source ID from missing page sharing.
• Pause a write queue on repeated conflicts inste…

Notion Content Change Control

Overview

Plan and verify safe Notion page, block, markdown, and file-content changes with previews and rollback evidence.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Current content operations distinguish pages, blocks, databases, and data sources. Block placement uses the current position object; current REST trash state and enhanced-markdown behavior must come from the selected version contract. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Use a connection with only the content capabilities needed for the approved scope. Confirm the exact parent and content-sharing path before any mutation.

Instructions

1. Resolve stable IDs and capture a pre-change snapshot, revision marker, and content owner.
2. Choose page properties, block operations, enhanced markdown, or file uploads based on the documented object contract.
3. Build a semantic preview showing creates, replacements, moves, and trash actions.
4. Validate payload size, nesting, unsupported blocks, file lifecycle, and version shape offline.
5. Apply the smallest approved change with idempotency and conflict detection.
6. Read back the changed scope and preserve rollback material until acceptance.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require content-owner approval for every write; require separate approval for replacement, move, trash, file upload, broad descendant access, or public sharing.

Error Handling

• Never replace an entire page when a bounded block or property update is sufficient.
• Do not reuse expiring download URLs as durable file identifiers.
• Stop on concurrent edits or an unexpected parent.

Output

Return the content manifest, semantic diff, approvals, applied IDs, read-back evidence, conflicts, and rollback package. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Append an approved section at the end of a page and verify its blocks.
• Trash a duplicate only after preserving its parent and restor…

Notion Data-Source Query Workflow

Overview

Analyze and query a Notion data source with version-correct filters, pagination, and completeness evidence.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Modern Notion APIs separate the database container from each data source schema. Query operations take a data-source ID; filters and sorts must match that data source's current property schema. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Opaque cursors are only for the next start_cursor request; never parse them or retain them as durable checkpoints or incident evidence.

Authentication

Use read-content capability and explicit access to the target content. Record the connection alias, not its bearer value.

Instructions

1. Retrieve database metadata and resolve the intended data-source ID by evidence, not name alone.
2. Retrieve the data-source schema and map requested fields to stable property IDs where practical.
3. Compile and review filters, sorts, page size, and output minimization.
4. Pass each cursor verbatim to the next request and record page counts. Check every response for request_status.type: incomplete; has_more: false alone does not prove completeness at the 10,000-result query cap.
5. Normalize page property values without assuming every property is populated or returned inline.
6. Reconcile row counts, duplicate IDs, missing pages, and acknowledged output. For full exports, use stable created_time windows with inclusive boundaries and record-ID deduplication; refuse nonadvancing or saturated tied boundaries and split further using the official large-source guide. Mutable last_edited_time is not a universal full-export checkpoint.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require the data owner before accessing a new data source, user information, sensitive properties, or an export destination.

Error Handling

• Do not pass a database ID where a data-source ID is required.
• Search is not a substitute for a scoped data-source …

Notion Idempotent Page Write Workflow

Overview

Create or update Notion pages and blocks with an idempotency key, semantic diff, and read-back verification.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Page properties follow the parent data source schema; page body content is a block tree or enhanced markdown. Current placement and trash semantics depend on the pinned API contract. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Use only insert or update content capability required by the operation. Confirm parent access and keep lookup identities separate from write identities when risk warrants.

Instructions

1. Resolve the exact parent, page, data source, and current revision.
2. Derive an idempotency key from the business object and operation version.
3. Render a semantic diff for properties, blocks, parent, and trash state.
4. Validate property types, relation targets, size limits, and block nesting offline.
5. Apply one approved mutation and persist the returned object ID before downstream work.
6. Read back the object, compare intended state, and retain compensation instructions.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require the content owner before insert, update, move, append, replacement, comment creation, or trash operations.

Error Handling

• Do not retry a timed-out create until searching the idempotency record.
• Do not coerce a property into a new type to make a payload pass.
• Stop if the parent or revision changed after approval.

Output

Return the target identity, idempotency key, pre-state, approved diff, response identity, read-back delta, and compensation plan. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Upsert one business record without duplicating it after a timeout.
• Append approved blocks and verify their order under the target page.

Validation

Exercise and record these paths with expected and observed results:

• duplicate retry
• s…

Notion Workload Cost and Waste Review

Overview

Reduce Notion integration waste across requests, workers, storage, and downstream processing without inventing API pricing.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Notion publishes operational limits, not a universal per-request price contract. Measure application infrastructure, queue, storage, observability, and downstream processor costs separately from Notion plan terms. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Opaque cursors are only for the next start_cursor request; never parse them or retain them as durable checkpoints or incident evidence.

Authentication

Use read-only telemetry and redacted request classes. Do not expose content or tokens to cost-analysis systems.

Instructions

1. Establish the workload owner, measurement window, freshness objective, and current cost allocation.
2. Count requests by operation, outcome, tenant, retry, page, and bytes without high-cardinality content labels.
3. Identify full scans, duplicate reads, unused fields, failed retries, polling overlap, and repeated transformations.
4. Model filtered queries, acknowledged record/time-window progress, webhook signals plus reconciliation, caching, and batching.
5. Rank changes by saved work, correctness risk, implementation effort, and rollback speed.
6. Pilot one change with freshness, completeness, error, and cost guardrails.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require data-owner approval for caching content, reducing freshness, changing retention, adding webhooks, or sharing telemetry with a vendor.

Error Handling

• Do not call an unpriced API request free.
• Do not reduce reconciliation until completeness evidence exists.
• Never cache sensitive page content merely to lower compute cost.

Output

Return the baseline, cost boundaries, waste ledger, ranked changes, expected range, pilot result, and rollback threshold. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

…

Notion Data Handling and Privacy Control

Overview

Define data classification, minimization, retention, and deletion controls for a Notion integration.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Notion page content, properties, comments, user objects, files, logs, and webhook metadata have different sensitivity and lifecycle characteristics. Connection capabilities and content sharing bound access but do not replace application governance. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Minimize content and user capabilities, separate tenants, and prohibit credentials or raw sensitive content in logs and fixtures.

Instructions

1. Map collection, purpose, lawful basis, classification, owner, processor, destination, and retention for every field class.
2. Minimize requested capabilities, selected properties, page bodies, user fields, and webhook subscriptions.
3. Define encryption, tenant isolation, logging, backup, export, correction, deletion, and legal-hold behavior.
4. Represent Notion trash, application deletion, destination deletion, and retained audit evidence as separate states.
5. Exercise subject and owner workflows on synthetic records before production.
6. Record residual risk, exceptions, expiry dates, and review owners.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require privacy, security, and data-owner approval before sensitive reads, external processing, historical export, retention change, or irreversible deletion.

Error Handling

• Do not infer deletion from a missing search result.
• Do not log page bodies to prove a privacy control.
• Freeze deletion when legal hold or object identity is unresolved.

Output

Return the data-flow map, field-class register, control matrix, retention schedule, deletion state machine, test evidence, and exceptions. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Export only approved properties for a subject request.
• Prove destination deletion while retainin…

Notion Redacted Debug Bundle

Overview

Assemble a reproducible, secret-free Notion integration diagnostic bundle for engineering or support.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Useful evidence includes dependency versions, selected API version, operation names, status and error codes, request identifiers, timings, retry decisions, and content-free object fingerprints. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Never collect bearer values, OAuth secrets, verification tokens, cookies, page content, user email, file URLs, or full request and response bodies by default.

Instructions

1. Define the incident window, affected operation, environment, tenant alias, and bundle recipient.
2. Collect dependency locks, redacted configuration keys, selected version, and runtime metadata.
3. Collect status, structured error code, request identifier, latency, retry count, and object-type fingerprints.
4. Run deterministic redaction and secret scanning over the staged bundle.
5. Generate a manifest with hashes, exclusions, collector version, and custody owner.
6. Review the final archive manually before approved transfer.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require the incident commander and data owner before collecting response excerpts or transmitting a bundle outside the approved boundary.

Error Handling

• Abort packaging if any secret pattern or raw content remains.
• A token prefix is still credential material; store only a one-way fingerprint.
• Do not broaden collection to unrelated tenants.

Output

Return the bundle manifest, hashes, redaction report, explicit exclusions, collection gaps, retention deadline, and transfer approval. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Package a 429 incident using timings and request IDs without page bodies.
• Prepare a vendor escalation with one approved redacted error envelope.

Validation

Exercise and record these paths with expected …

Notion Integration Deployment Control

Overview

Prepare and verify a Notion integration deployment with environment isolation, secret provenance, staged rollout, and rollback.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Deployment readiness depends on the tested SDK and API contract, connection configuration, shared fixture content, worker or queue topology, and rollback compatibility; a successful build is not a production acceptance test. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Bind each environment to distinct secret references and Notion connections. Never copy development tokens into production or expose secrets to preview builds.

Instructions

1. Pin the artifact digest, dependency lock, selected API version, schema assumptions, and migration order.
2. Verify environment-specific connection, content access, webhook destination, queue, and observability bindings.
3. Run offline contract tests and a non-production read-only smoke test.
4. Produce a rollout plan with canary scope, concurrency, retry, write, and reconciliation guards.
5. Deploy only through the approved platform workflow and observe defined health signals.
6. Reconcile output and either promote or execute the tested rollback.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require release-owner approval for production deployment and separate content-owner approval before enabling writes, subscriptions, or backfills.

Error Handling

• Do not accept a health endpoint that never touches the configured dependency contract.
• Do not rotate a token and deploy code in one unreviewable step.
• Rollback if object-shape or reconciliation checks diverge.

Output

Return the artifact and configuration receipts, gate matrix, rollout observations, reconciliation result, and rollback outcome. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Canary a read-only query before enabling a write worker.
• Roll back a version migration when fixture and live sh…

Notion Enterprise Authorization Boundary Review

Overview

Map Notion connection capabilities, content access, user context, and application roles into an auditable authorization model.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Notion connection capabilities, page sharing, installer authority, personal-token user permissions, application roles, and enterprise admin APIs are distinct control planes. None should be presented as universal Notion RBAC. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Record internal connection, public OAuth connection, or personal access token explicitly. For public OAuth, bind encrypted tokens and refresh state to the correct workspace and installation.

Instructions

1. Inventory actors, workspace and tenant boundaries, connection types, capabilities, shared roots, and application roles.
2. Build an operation matrix for read, insert, update, comments, user information, webhook, and administrative surfaces.
3. Calculate effective access as the intersection of token model, capabilities, content sharing, user authority, and application policy.
4. Design authorization checks at every job, cache, queue, and destination boundary.
5. Add joiner, mover, leaver, reauthorization, revocation, and workspace-removal workflows.
6. Review exceptions, separation of duties, audit evidence, and recertification cadence.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require workspace admin, security, and data-owner approval for new capabilities, workspace-wide access, user-email access, administrative APIs, or cross-workspace processing.

Error Handling

• Do not equate a successful token exchange with access to all workspace content.
• Do not use application roles to conceal an overprivileged Notion token.
• Fail closed when workspace binding is missing.

Output

Return the actor-resource-operation matrix, effective-access rules, tenant-binding model, lifecycle workflows, exceptions, and recertification owner. Identify assumptions, owners, expirations, and evidence ga…

Notion Read-Only Connection Proof

Overview

Prove a Notion connection, API version, and shared-content boundary with a minimal read-only check.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

The smallest safe proof identifies the bot or token context and retrieves one explicitly shared non-sensitive fixture. Search results alone do not prove access to arbitrary workspace content. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Use an approved non-production bearer secret through the runtime secret store. Record only its connection alias and one-way fingerprint.

Instructions

1. Confirm the connection type, environment, token owner, and selected tested API version.
2. Share one synthetic fixture page or data source with read-only capability.
3. Retrieve the current bot identity and record content-free metadata.
4. Retrieve the fixture by its exact ID and confirm the expected object type.
5. Exercise one denied path against an intentionally unshared fixture.
6. Remove temporary access if created and preserve the redacted proof.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require the workspace owner before creating a connection or sharing content; do not create or modify pages in this workflow.

Error Handling

• A 200 response from bot identity does not prove content access.
• Do not paste the token into a command history or artifact.
• Stop if the fixture contains real workspace data.

Output

Return the connection alias, environment, selected version, bot fingerprint, fixture identity, allow/deny results, and cleanup receipt. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Prove access to one synthetic page and denial of an unshared page.
• Verify a data-source identity without querying business rows.

Validation

Exercise and record these paths with expected and observed results:

• valid token
• revoked token
• shared fixture
• unshared fixture
• wrong …

Notion Integration Incident Command

Overview

Analyze and coordinate a Notion integration incident with bounded mitigation, evidence custody, communications, and recovery verification.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Separate Notion service health, authentication, access, version shape, application defects, queues, downstream systems, and data correctness. Availability recovery does not prove data reconciliation. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Opaque cursors are only for the next start_cursor request; never parse them or retain them as durable checkpoints or incident evidence.

Authentication

If compromise is suspected, freeze token use and follow the approved secret-rotation lane; never expose credentials in the incident channel.

Instructions

1. Name the incident commander, severity, affected tenants, operations, data classes, and start time.
2. Freeze unsafe writes and retries while preserving content-safe queue progress, acknowledged record IDs, request-ID, and deployment evidence.
3. Classify the fault domain and compare official status with application telemetry.
4. Choose the smallest reversible mitigation with an owner and rollback trigger.
5. Restore service in stages, then reconcile pages, fresh queries, webhook signals, duplicates, and missed work.
6. Close only after security, data correctness, communications, and follow-up ownership are evidenced.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

The incident commander approves mitigation; security approves token actions; content and data owners approve replay, backfill, or destructive correction.

Error Handling

• Do not replay a write queue before idempotency is proven.
• Do not blame the vendor solely from correlated timing.
• Escalate immediately on suspected cross-tenant or credential exposure.

Output

Return the timeline, scope, evidence, hypotheses, decisions, mitigation, reconciliation ledger, communications, and follow-ups. Identify assumptions, owners, expirations, and evidenc…

Notion Connection and Authentication Intake

Overview

Establish a least-privilege Notion connection and tested API contract without leaking credentials.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Notion supports internal connections, public OAuth connections, and personal access tokens with different ownership and access behavior. REST calls require bearer authentication and an explicit tested Notion-Version contract. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Record credential issuer, connection or user owner, workspace binding, capabilities, shared roots, expiry or refresh behavior, storage, rotation, and revocation without storing the secret value.

Instructions

1. Choose the connection type from distribution, tenant, and user-context requirements.
2. Define the minimum content, comment, and user capabilities plus exact shared fixture roots.
3. Select and test an SDK and API-version combination against current upgrade guidance.
4. Provision the credential through the approved secret manager and record a fingerprint.
5. Run bot identity plus one explicitly shared read-only fixture check.
6. Document rotation, OAuth refresh if applicable, revocation, reauthorization, and production promotion.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require the workspace owner for connection creation and sharing; require security review for public OAuth, user information, external distribution, or production secrets.

Error Handling

• Never infer OAuth scopes or redirect behavior from an internal token example.
• A connection capability does not grant access until content is shared where required.
• Do not commit env files or access tokens.

Output

Return the connection model, workspace binding, capability matrix, shared roots, secret reference, validation evidence, lifecycle owners, and gaps. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Onboard a read-only internal connection to a synthetic data source.
• Docum…

Notion Integration Pitfall Review

Overview

Audit a Notion integration for recurring identity, access, version, pagination, webhook, and mutation mistakes.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Common failures arise from confusing databases with data sources, assuming capabilities equal content access, omitting pagination, pinning stale object shapes, treating webhooks as a ledger, or retrying writes without idempotency. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Check that the code distinguishes connection models, workspace binding, capabilities, shared content, and secret lifecycle.

Instructions

1. Inventory all Notion clients, selected versions, tokens, object IDs, operations, and data flows.
2. Trace every database, data-source, page, block, file, search, and webhook assumption to first-party docs or a fixture.
3. Check pagination, size limits, unknown fields, error classes, Retry-After, and retry budgets.
4. Check idempotency, pre-state, read-back, compensation, and destructive-action approvals.
5. Check webhook signature, duplicate, ordering, aggregation, fetch-current, and reconciliation behavior.
6. Rank findings by exploitability, data impact, recurrence, and ease of correction.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require approval before using live credentials or content to confirm a suspected pitfall; repository inspection remains read-only by default.

Error Handling

• Do not fix a 404 by broadening access without proving identity.
• Do not assume a single search or query page is complete.
• Do not silently coerce legacy payloads into current writes.

Output

Return the pitfall inventory, evidence, impact, false-positive notes, corrective action, owner, and verification test. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Find a database ID passed to a data-source query.
• Find a webhook handler that trusts delivery order and never reconciles.

Validation

Exerci…

Notion Capacity and Backpressure Planning

Overview

Plan and test Notion workload capacity within observed limits without evading per-connection controls.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Notion documents an average request rate and payload limits but may change quotas. Capacity planning must honor Retry-After, response latency, page size, pagination depth, downstream pressure, and tenant fairness. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Opaque cursors are only for the next start_cursor request; never parse them or retain them as durable checkpoints or incident evidence.

Authentication

Use synthetic non-production content and one approved test connection. Additional tokens are not a sharding mechanism for bypassing limits.

Instructions

1. Define volume, freshness, concurrency, burst, payload, tenant, and recovery objectives.
2. Measure a low-rate baseline by operation using synthetic fixtures.
3. Model request amplification from pagination, block recursion, retries, reconciliation, and downstream failures.
4. Introduce queue rate control, tenant fairness, bounded concurrency, and backpressure.
5. Increase load in approved stages while observing 429, Retry-After, latency, errors, queue age, and completeness.
6. Set safe operating limits, saturation alarms, degradation behavior, and rollback thresholds.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require platform and workspace-owner approval for load tests; never run them against production content or multiply credentials to raise throughput.

Error Handling

• Stop when error, latency, queue age, or Retry-After exceeds the stage threshold.
• Do not treat burst success as sustained capacity.
• Preserve acknowledged record progress and destination receipts when downstream systems fail; restart with a fresh query and deduplication.

Output

Return the workload model, measured curve, amplification factors, safe envelope, fairness policy, degradation plan, and rollback threshold. Identify assumptions, owners,…

Notion Isolated Local Development Loop

Overview

Create a repeatable local Notion development loop using fixtures, mocks, and an explicitly shared sandbox.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Local tests should model the selected API version, pagination, errors, additive fields, data-source identities, and current write semantics. A sandbox smoke test complements but does not replace deterministic fixtures. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Use a dedicated sandbox connection and secret store reference. Never copy production tokens, page IDs, exports, or response bodies into fixtures.

Instructions

1. Pin the SDK, selected API version, runtime, and fixture schema.
2. Create synthetic page, data-source, block, webhook, limit, and error fixtures with secret canaries.
3. Wrap the client behind an operation boundary that records status and request IDs without content.
4. Implement offline unit and contract tests before a live sandbox check.
5. Run one bounded read and, only when approved, one reversible sandbox write.
6. Reset fixtures, verify no production identifiers entered the workspace, and preserve test evidence.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require the sandbox owner before any live call and explicit approval for writes, webhooks, file uploads, or destructive reset.

Error Handling

• Do not record live responses as fixtures without classification and redaction.
• Do not make tests depend on search propagation timing.
• Fail if configuration points to a production connection or object.

Output

Return the environment contract, fixture manifest, test commands, sandbox access map, live-check receipt, and cleanup status. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Develop a data-source query entirely from synthetic multi-page fixtures.
• Exercise a page write in a sandbox and restore its original state.

Validation

Exercise and record these paths with expe…

Notion Migration Reconciliation

Overview

Design and execute a reversible Notion content or schema migration with identity maps, checkpoints, and reconciliation.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Migration contracts must distinguish database containers, data sources, pages, properties, blocks, files, users, relations, and trash state. Search and export order are not durable migration checkpoints. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Use separate least-privilege source-read and destination-write identities where possible. Keep identity maps and sensitive content encrypted and tenant-scoped.

Instructions

1. Freeze the source and destination contracts, selected versions, owners, and acceptance metrics.
2. Inventory schemas, stable IDs, relations, unsupported blocks, files, user mappings, and sensitive fields.
3. Create deterministic identity, property, relation, content, and lifecycle mappings with quarantine rules.
4. Run a synthetic dry run and then a small approved canary with resumable checkpoints.
5. Migrate in bounded batches; persist destination IDs before advancing source checkpoints.
6. Reconcile counts, hashes, relations, block order, files, quarantines, late changes, and rollback eligibility.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require source and destination owners before reads or writes; require separate approval for historical export, user data, backfill, trash, or cutover.

Error Handling

• Do not use titles as unique identities.
• Do not advance a checkpoint after partial destination acknowledgement.
• Freeze cutover on unexplained count or relation drift.

Output

Return the contracts, mappings, checkpoints, batch ledger, reconciliation, quarantine, cutover decision, and rollback package. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Migrate one legacy database schema to current data-source operations.
• Resume a cross-workspace page migration without duplicating a…

Notion Multi-Environment Isolation

Overview

Define isolated development, staging, and production Notion connections, secrets, content roots, and promotion rules.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Notion has no universal environment abstraction for integrations. Isolation comes from distinct connections or tokens, workspace/content boundaries, secrets, destinations, queues, webhooks, and application guards. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Provision unique secret references and fingerprints per environment. Never fall back from a missing non-production secret to production.

Instructions

1. Inventory each environment's workspace, connection, owner, capabilities, shared roots, webhook, queue, and destination.
2. Define immutable environment identifiers and fail-closed startup assertions.
3. Separate secrets, object IDs, callback URLs, encryption keys, and telemetry labels.
4. Use synthetic fixtures outside production and prevent configuration fallbacks.
5. Promote code artifacts independently from credentials and content configuration.
6. Run cross-environment leak tests and record rotation, teardown, and break-glass owners.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require each workspace owner before sharing content; require release approval for production binding and security approval for break-glass access.

Error Handling

• Abort if two environments share a credential fingerprint.
• Do not infer environment from a page title or hostname alone.
• Never copy production exports into lower environments without governance.

Output

Return the environment matrix, fingerprints, shared-root map, promotion gates, leak-test results, lifecycle owners, and exceptions. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Prove staging cannot retrieve a production fixture.
• Promote one artifact while retaining distinct environment credentials.

Validation

Exercise and record th…

Notion Integration Observability Contract

Overview

Design content-safe metrics, logs, traces, alerts, and reconciliation signals for a Notion integration.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Operational signals should distinguish operation class, status, structured code, request ID, latency, retry, queue age, cursor age, and reconciliation delta. Page IDs, titles, content, user data, tokens, and signed URLs are unsafe default labels. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Telemetry pipelines receive no bearer or verification tokens. Use tenant aliases and bounded fingerprints approved for the monitoring boundary.

Instructions

1. Define service, freshness, correctness, and security objectives with owners.
2. Create a low-cardinality operation taxonomy covering reads, writes, webhooks, queues, files, and reconciliation.
3. Specify redaction before serialization and sampling after security events are preserved.
4. Correlate attempts with internal operation IDs and vendor request IDs without content.
5. Alert on sustained error class, Retry-After pressure, queue age, cursor staleness, and reconciliation drift.
6. Exercise dashboards and alerts with synthetic failures and document response ownership.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require data and security approval before adding identifiers, payload excerpts, user fields, or third-party telemetry processors.

Error Handling

• Do not use page or workspace IDs as unbounded metric labels.
• A green request-rate dashboard does not prove sync completeness.
• Fail closed if redaction is unavailable.

Output

Return the signal catalog, redaction contract, objective definitions, dashboards, alerts, runbook links, and test receipts. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Alert on cursor age even when requests return 200.
• Trace a retry chain with request IDs but no page content.

Validation

Exercise and record these…

Notion Evidence-Driven Performance Tuning

Overview

Improve Notion integration latency and throughput while preserving completeness, fairness, and limit compliance.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Performance depends on operation type, pagination and recursion, response size, rate pressure, network latency, queueing, downstream processing, and cache behavior. The observed bottleneck must select the optimization. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Use redacted telemetry and synthetic benchmarks. Content caches require classification, encryption, tenant isolation, expiry, and deletion behavior.

Instructions

1. Record latency distributions, requests per business operation, pages, bytes, errors, retries, and queue wait.
2. Identify whether the constraint is Notion calls, pagination, block recursion, transformation, cache, queue, or destination.
3. Choose one intervention: narrower query, checkpoint, concurrency bound, cache, batch, webhook signal, or downstream optimization.
4. State consistency, freshness, completeness, fairness, and memory tradeoffs.
5. Canary against a representative synthetic or approved non-production workload.
6. Compare before and after, exercise rollback, and reject regressions hidden by averages.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require approval before caching content, increasing concurrency, changing freshness, adding subscriptions, or benchmarking a live tenant.

Error Handling

• Do not parallelize until Retry-After and tenant fairness are enforced.
• Do not optimize away required pagination or reconciliation.
• Stop if tail latency, error rate, or completeness worsens.

Output

Return the baseline, bottleneck evidence, experiment, tradeoffs, measured result, safe envelope, and rollback threshold. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Reduce block-recursion amplification by fetching only required page content.
• Cache stable schema metadat…

Notion Integration Policy Guardrails

Overview

Turn Notion security, privacy, access, version, and mutation rules into enforceable repository and runtime gates.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Useful guardrails cover secret handling, tested versions, object-type correctness, pagination, retries, capabilities, content sharing, tenant binding, webhook verification, destructive actions, and evidence retention. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Policy checks may inspect secret names and fingerprints but never values. Runtime checks must bind a credential to its expected workspace and environment.

Instructions

1. Translate each policy statement into owner, scope, machine check, human gate, evidence, and exception expiry.
2. Add static checks for credentials, legacy object operations, unsafe logging, unbounded retries, and missing approvals.
3. Add tests for page/data-source identity, pagination, webhook signatures, idempotency, and tenant isolation.
4. Add runtime guards for environment, write scope, concurrency, payload size, and destructive operations.
5. Define signed, time-bounded exceptions with compensating controls.
6. Exercise allow, deny, bypass-expired, and rollback paths before enforcing the gate.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Security owns secret and webhook rules; data owners own content scope; release owners approve enforcement rollout; no single actor self-approves exceptions.

Error Handling

• A warning-only secret rule is insufficient for production.
• Do not auto-fix object identity or destructive requests.
• Fail closed when policy evidence is missing.

Output

Return the control catalog, implementation points, tests, gate outputs, exception register, owners, and rollout plan. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Block a credential literal before commit.
• Reject a write job lacking an approved scope and idempotency key.

Validation

Notion Production Readiness Review

Overview

Decide whether a Notion integration is ready for production from evidence across access, contracts, correctness, safety, and operations.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Readiness covers selected API and SDK contracts, connection model, access, schema and object identities, pagination, limits, retries, idempotency, webhooks, data governance, observability, reconciliation, and rollback. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Verify production secret provenance, workspace binding, minimum capabilities, shared roots, rotation, revocation, and break-glass custody.

Instructions

1. Bind the review to an immutable artifact, configuration digest, owners, environments, and change window.
2. Walk access, data, version, schema, operation, limit, retry, webhook, and destructive-action controls.
3. Run offline tests and approved non-production happy, denied, failure, restart, and rollback paths.
4. Verify dashboards, alerts, incident ownership, support escalation, queue controls, and reconciliation.
5. List open risks with explicit acceptance authority and expiry.
6. Issue GO, CONDITIONAL GO, or NO-GO with evidence and post-launch observation gates.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Production owner approves launch; security, data, and content owners approve their boundaries; destructive or irreversible migrations require an independent gate.

Error Handling

• A Grade A document is not operational readiness evidence.
• Do not waive missing rollback or reconciliation as follow-up work.
• NO-GO when production identity or secret provenance is ambiguous.

Output

Return the signed gate matrix, evidence links, risks, decision, launch window, rollback triggers, and observation plan. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Issue NO-GO for a write worker without idempotency tests.
• Issue CONDITIONAL GO for a read-only canary with a bounded follo…

Notion Rate-Limit and Retry Control

Overview

Implement adaptive Notion request throttling and bounded retry behavior from observed responses.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Notion documents an average per-connection request rate, allows some bursts, returns 429 for rate pressure, and supplies Retry-After. Limits may change, so the runtime response is authoritative. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Throttle by approved connection and tenant boundary; never log tokens or create extra credentials to bypass a limit.

Instructions

1. Measure requests by operation, tenant, outcome, Retry-After, latency, retry, and queue age.
2. Classify retryable rate and transient service failures separately from permanent input or access failures.
3. Use a shared limiter with bounded concurrency, tenant fairness, jitter, and a strict attempt and elapsed-time budget.
4. Honor Retry-After as the minimum wait and reduce future pressure after repeated limits.
5. Preserve idempotency and acknowledgement state before retrying writes.
6. Test recovery, saturation, cancellation, restart, and downstream backpressure.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require platform approval before increasing concurrency or queue depth; require operation-owner approval before replaying writes or changing freshness objectives.

Error Handling

• Never retry every 4xx response.
• Do not sleep while holding an unrenewed job lease.
• Stop and shed or defer load when the retry budget is exhausted.

Output

Return the limiter policy, retry matrix, fairness model, measurements, saturation behavior, and rollback configuration. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Honor a larger Retry-After value than the local backoff produced.
• Quarantine a permanent validation error instead of retrying it.

Validation

Exercise and record these paths with expected and observed results:

• burst
…

Notion Integration Reference Architecture

Overview

Define a production reference architecture for Notion access, operations, queues, reconciliation, and evidence.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

A durable architecture separates transport, auth, tenant binding, object identity, schema mapping, operation logic, queues, idempotency, webhooks, reconciliation, telemetry, and evidence storage. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Centralize secret retrieval without centralizing plaintext. Bind every operation to connection, workspace, environment, capabilities, and approved content scope.

Instructions

1. Define domain boundaries, sources of truth, tenant model, data classes, and service objectives.
2. Specify adapters for current pages, blocks, databases, data sources, search, files, and webhooks.
3. Place idempotency, checkpoints, backpressure, retry classification, and dead letters at explicit boundaries.
4. Add reconciliation as a first-class service independent of webhook delivery.
5. Define observability, evidence, privacy, retention, incident, and support interfaces.
6. Document deployment stages, compatibility policy, failure modes, and tested rollback.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require architecture, security, and data-owner review before adopting shared tokens, shared queues, external processors, or cross-tenant stores.

Error Handling

• Do not leak SDK response shapes directly into domain models.
• Do not make webhook delivery the only recovery path.
• Reject shared mutable state without tenant binding.

Output

Return context and component views, contracts, trust boundaries, failure modes, capacity assumptions, operational ownership, and rollout plan. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Standardize query and write adapters behind domain operations.
• Recover missed webhook signals through scheduled reconciliation.

Validation

Exercise …

Notion Reliability Pattern Selection

Overview

Analyze and apply retry, idempotency, checkpoint, circuit, dead-letter, and reconciliation patterns to a specific Notion operation.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Reliability behavior depends on whether an operation is a read, create, update, webhook signal, paginated extraction, file lifecycle, or downstream side effect. Retry safety cannot be inferred from HTTP method alone. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Recovery stores and dead letters must protect workspace content and tenant identifiers to the same standard as the primary system.

Instructions

1. Define success, acknowledgement, idempotency identity, checkpoint, timeout ambiguity, and compensation for the operation.
2. Classify permanent, transient, rate, conflict, access, and unknown failures.
3. Select bounded retry, idempotency record, lease, circuit, dead letter, or reconciliation only where its invariant is explicit.
4. Persist response identity before acknowledging creates and destination state before advancing read checkpoints.
5. Exercise duplicate, reorder, timeout, crash, poison item, and partial downstream failure.
6. Document operator recovery, replay authorization, observability, and rollback.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require operation-owner approval for dead-letter replay, checkpoint rewind, backfill, compensation, or bypassing a circuit. Record the approver and bounded recovery window before execution.

Error Handling

• Do not retry a timed-out create without deduplication evidence.
• Do not drop poison items to keep a queue green.
• Do not use stale cached content as an authoritative write source.

Output

Return the operation state machine, invariants, retry matrix, recovery stores, test evidence, runbook, and residual risks. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Recover a timed-out page create without duplication.
• Resume a multi-…

Notion SDK Contract Patterns

Overview

Build a version-aware Notion SDK boundary with typed operations, pagination, error classification, and test seams.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

The official JavaScript SDK exposes current database, data-source, page, block, file, search, and auth operations. Pin and test an SDK/API combination; tolerate additive response fields and isolate vendor shapes. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Construct clients from a secret provider and tenant-bound connection profile. Never accept raw credentials through business-method arguments or return them in errors.

Instructions

1. Define a narrow interface in domain terms rather than exporting the entire SDK client.
2. Pin the SDK and selected tested API version with an upgrade matrix.
3. Implement data-source identity resolution, complete pagination, property decoding, and unknown-field tolerance.
4. Classify structured errors and Retry-After before applying bounded retry.
5. Add idempotency and read-back at write boundaries, not inside generic transport retry.
6. Test adapters with fixtures plus a bounded non-production contract lane.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require review before exposing a new operation, capability, user field, content type, or live-write test.

Error Handling

• Do not cast legacy database-query responses into current data-source types.
• Do not retry all SDK exceptions.
• Do not let an SDK default silently choose the production API contract.

Output

Return the interface, dependency and version pins, adapters, error map, pagination helper, write invariants, and contract tests. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Wrap a data-source query behind a paginated domain iterator.
• Decode unknown additive fields without failing the whole response.

Validation

Exercise and record these paths with expected and observed results:

• …

Notion Search and Retrieval Workflow

Overview

Analyze search intent and retrieve explicitly shared Notion pages or data sources while respecting search limitations and object identity.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Current search returns shared pages and data sources, is title-oriented, paginated, and not guaranteed to reflect changes immediately. A specific structured dataset should be queried through its data-source endpoint instead. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Use read capability and an approved shared-content scope. User fields and page bodies need separate minimization decisions.

Instructions

1. Clarify whether the operator knows an exact ID, title fragment, database, or data-source identity.
2. Prefer exact-ID retrieval when provenance exists; otherwise run a type-scoped paginated search.
3. Record every page of candidates and disambiguate by object type, parent, and stable ID.
4. Retrieve only approved metadata, properties, blocks, or markdown required by the task.
5. Recursively traverse blocks only when requested and with depth, page, and byte bounds.
6. Return completeness limits, access gaps, and the selected object's evidence.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require the content owner before reading page bodies, user information, sensitive properties, descendants, or files beyond the approved scope.

Error Handling

• Do not interpret no search result as proof that content does not exist.
• Do not use a database ID as a data-source query target.
• Stop recursive retrieval at the approved depth or byte budget.

Output

Return the search plan, paginated candidates, chosen stable IDs, retrieval manifest, truncation, access gaps, and evidence date. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Disambiguate two pages with the same title using parent and ID.
• Retrieve a page's approved blocks without following unrelated links.

Validation

Notion Integration Security Baseline

Overview

Establish a security baseline for Notion credentials, capabilities, content access, webhooks, writes, logs, and tenant isolation.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Security spans bearer-token custody, OAuth state and workspace binding, minimum capabilities, explicit content sharing, webhook signature verification, version-safe parsing, idempotent writes, telemetry redaction, and incident revocation. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Store credentials only in the approved secret system, encrypt public-connection tokens at rest, separate environments and tenants, and test rotation and revocation.

Instructions

1. Inventory connections, owners, workspaces, capabilities, shared roots, secrets, callbacks, subscriptions, and processors.
2. Minimize access and prove denied paths for unshared or unauthorized content.
3. Threat-model OAuth state, callback binding, token storage, webhook verification, replay, SSRF, logs, caches, queues, and exports.
4. Add payload validation, unknown-field tolerance, request limits, retry budgets, idempotency, and destructive-action gates.
5. Instrument content-safe security events and define credential-compromise containment.
6. Exercise rotation, revocation, tenant swap, forged webhook, over-limit payload, and rollback.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Security and workspace owners approve connection and capability changes; data owners approve content scope; production writes require operation-owner approval.

Error Handling

• Never log bearer or webhook verification material.
• Do not trust a workspace ID supplied by an unbound client session.
• Reject webhook signatures using constant-time comparison after hashing the raw body.

Output

Return the threat model, access matrix, secret lifecycle, control evidence, test results, exceptions, and incident contacts. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• R…

Notion SDK and API Upgrade Control

Overview

Upgrade a Notion integration across SDK or API contracts with inventory, compatibility tests, staged rollout, and rollback.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Recent contracts separated databases from data sources and changed search filters; the current contract also changes block placement, trash state, and a meeting-note block identity. SDK support and API opt-in are related but separate choices. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Run upgrade tests with a dedicated non-production connection and synthetic content. Never rotate production credentials merely to test compatibility.

Instructions

1. Inventory every client, explicit or default API version, SDK pin, operation, object type, fixture, and webhook subscription version.
2. Read both intervening first-party upgrade guides and build a before/after contract matrix.
3. Replace database-query assumptions with data-source identities and update search and schema operations.
4. Update current block position, trash-state, and meeting-note handling plus unknown-field tolerance.
5. Run offline fixtures, dual-read comparisons, denied paths, reversible sandbox writes, and rollback tests.
6. Canary one bounded workload, reconcile results, and promote only with a retained rollback artifact.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require release approval for version or SDK promotion and content-owner approval for any live compatibility write or migration.

Error Handling

• Do not update the SDK and silently inherit a new API contract.
• Do not cast old fixtures into new types to make tests pass.
• Rollback on object-identity, trash-state, or reconciliation divergence.

Output

Return the inventory, contract delta, code and fixture changes, compatibility matrix, canary evidence, decision, and rollback package. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples

• Migrate a database query to a data-source query …

Notion Webhook Intake and Reconciliation

Overview

Implement verified Notion connection-webhook intake with deduplication, bounded processing, and fetch-current reconciliation.. This workflow produces an auditable decision or artifact before any live action.

Prerequisites

• Current first-party Notion documentation and the selected integration's tested API-version contract.
• A named workspace owner, content or data owner, and operation owner.
• Synthetic or approved non-production fixtures with secrets and workspace content removed.

Current Contract

Notion verifies a subscription with a one-time token and signs later raw request bodies in X-Notion-Signature using HMAC-SHA256. Events can aggregate, arrive out of order, and omit full changed content; fetch current state and reconcile. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.

Authentication

Store verification material as a secret, hash the exact raw body, compare signatures in constant time, bind the subscription to the expected connection, and rotate through an approved recreate path.

Instructions

1. Define subscribed event types, data owner, destination, retention, and current subscription API version.
2. Implement the verification handshake without logging or echoing the token beyond the required portal step.
3. Verify the raw-body signature before JSON parsing or queue acknowledgement.
4. Persist a deduplication key, event timestamp, entity identity, attempt, and processing state with tenant binding.
5. Acknowledge quickly, process asynchronously, fetch current state, and make downstream work idempotent.
6. Reconcile periodically for missed, aggregated, reordered, duplicated, or stale signals.

Tool Discipline

Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.

Approval Boundaries

Require workspace and data-owner approval to create, change, or delete a subscription; replay, backfill, and downstream writes require separate approval.

Error Handling

• Reject missing or malformed signatures before parsing.
• Do not trust delivery order or use the event payload as full current content.
• Quarantine unknown event types while preserving a content-safe receipt.

Output

Return the subscription contract, verification evidence, event-state model, deduplication policy, reconciliation plan, tests, and rotation runbook. Identify assumptions, owners, expirations, and evidence gaps explicitly.

Examples