Skip to main content

​
Mintlify Docs Agent

​
Overview

For each Needs Review entry in the Notion database: create a branch, make the necessary Markdown changes, open a PR, and update the Notion record with what was done. Each feature gets its own branch and PR. This repository is a Mintlify documentation site. Prefer editing existing .mdx docs under docs/ and update mint.json or docs.json when navigation or page structure changes are required.

​
Step 1 - Fetch Notion Records

Query the Notion database for all records where Doc Status = Needs Review.
  • Database: Feature Notes - PR Scanner
  • Data Source ID: collection://97e6a715-e2fe-4dd6-b9bb-c2ccc19a5080
For each record, read: Feature Name, Change Type, Affected Area, Summary for Docs Team, Suggested Doc Actions, Key Details, Open Questions, and Feature Complete?.

​
Step 2 - Create a Branch

Before touching any files, create a new git branch for this feature:
  • Branch off main (or the repo’s default branch)
  • Branch naming convention: docs/<kebab-case-feature-name>
    • Example: docs/digest-email-frequency-setting
  • One branch per Notion record (or per distinct feature if a record covers multiple)
git checkout main
git pull
git checkout -b docs/<feature-name>

​
Step 3 - Scan the Repo

Search the repo’s .mdx file tree for the most relevant existing file(s). Match by:
  • Affected Area (primary signal)
  • Feature names, parameter names, and UI labels from Key Details
  • Section headings and existing content
Read the full content of any candidate files before deciding what to do.

​
Step 4 - Make the Changes

Choose the appropriate action and execute it directly on the branch:
ScenarioAction
Feature is standalone with no natural homeCreate a new .mdx file
Existing article covers the area but lacks this featureAdd a new section
Existing article covers this feature but is outdatedModify existing content
Removal change makes an entire article obsoleteDelete the file
Removal change makes one section obsoleteRemove that section
Docs already accurately cover this featureNo action - skip PR, delete branch
Prefer extending existing articles over creating new ones.

​
Creating a new file

  • Follow existing naming conventions: lowercase, hyphenated (for example digest-email-settings.mdx)
  • Place it in the directory where similar content lives
  • Include Mintlify-compatible frontmatter (title, description) matching existing files
  • Write complete, publish-ready content - not a stub
  • Update mint.json or docs.json when navigation or file structure changes

​
Modifying or extending an existing file

  • Make targeted edits only - don’t rewrite sections that don’t need to change
  • Add new sections after the most closely related existing section
  • Use exact terminology from Key Details - never paraphrase product names or labels
  • Remove or update outdated deprecation notices as appropriate

​
Deleting content

  • For a full file deletion, remove the file and clean up any references in mint.json or docs.json
  • For a section removal, delete the section and ensure surrounding content flows logically

​
Writing style

  • Second person (“you can”, “your workspace”)
  • Concise - this is reference material, not marketing copy
  • Match heading levels and callout styles used in the rest of the repo
  • Use exact feature names, UI labels, and parameter names from Key Details

​
If Feature Complete? is In Progress or Uncertain

  • Proceed with changes but add a visible callout at the top of any new or modified content: > **Note:** This feature may still be rolling out.
  • Flag this prominently in the PR description and in Doc Agent Notes

​
Step 5 - Commit and Open a PR

Once changes are made, commit and push the branch: 
git add .
git commit -m "docs: <short description of what changed> [<Feature Name>]"
git push origin docs/<feature-name>
Then open a PR with:
  • Title: docs: <Feature Name>
  • Base branch: main
  • Body: Use this template:
## What changed
<2-3 sentences from the Notion Summary for Docs Team field>

## Files affected
- `path/to/file.mdx` - <one line describing what changed>

## Notion record
<link to the Notion record>

## Notes
<Paste any content from Open Questions or Doc Agent Notes>
<If Feature Complete? is In Progress or Uncertain, call that out prominently here>

​
Step 6 - Update the Notion Record

After the PR is open, update the Notion record:
FieldValue
Doc ActionCreate New Article, Modify Existing Article, Delete Article, Add Section to Existing, or No Action Needed
Target File PathRepo-relative path of the file modified or deleted
Suggested File PathRepo-relative path of any new file created
Changes MadePlain-English summary of what changed: which file, which section, what was added/removed/updated
Doc Agent NotesJudgment calls, edge cases, or anything a human reviewer should check before merging
Doc PR LinkURL of the opened PR
Doc StatusIn Progress (moves to Updated only after the PR is merged)

​
Edge Cases

  • Open Questions is populated: Use your best judgment, surface the questions in the PR body, and note them in Doc Agent Notes. Do not block on unanswered questions.
  • Multiple files affected: Update all of them in the same branch and PR. List each in Changes Made.
  • No relevant file found: Create a new file. Do not leave a feature undocumented.
  • Content conflicts with other existing docs: Resolve in favor of the new feature information. Note the conflict in the PR body and Doc Agent Notes.
  • Nav or config updates needed: Make them in the same branch. List the files in the PR body.
  • No action needed: Do not open a PR. Delete the branch. Set Doc Status to No Action Needed in Notion.

​
Output Per Record

After completing each record confirm: 
+ [Feature Name] -> [Action] - [File path(s)] - PR: [PR URL]
Or if no action was needed: 
- [Feature Name] -> No action needed - branch deleted