Context
The sync_all MCP tool currently synchronizes GitHub issues and releases with local Markdown files. However, running sync_all on a feature branch results in pulling new Markdown files that haven't been merged to dev into the current branch, polluting the feature branch with unrelated documentation commits.
The Problem
Running sync_all inside a feature branch introduces unrelated issue metadata files, making the PR noisy and entangling documentation sync commits with feature code commits. This was empirically observed in a recent PR where unrelated markdown file updates were absorbed into a feature branch because sync_all was executed prior to checking out dev.
The Architectural Reality
The tool description in ai/mcp/server/github-workflow/openapi.yaml for sync_all lacks a constraint regarding which branch it should be invoked in. Agents rely heavily on these tool descriptions (the prompt) to understand operational constraints.
The Fix
Update the tool description for sync_all in openapi.yaml to explicitly state:
- Branch Constraint: ONLY use this tool inside the
dev branch. The tool creates and updates local markdown files based on GitHub content; running it on a feature branch will pollute the branch with unrelated documentation commits.
Acceptance Criteria
Out of Scope
- Modifying the underlying behavior of
sync_all in SyncService.mjs (e.g., adding branching logic or preventing execution automatically by reading .git/HEAD). A simple prompt engineering / tool description update suffices for now.
Avoided Traps
- Attempting to make the MCP server aware of the local git branch to reject the command automatically. This adds unnecessary complexity where an updated description serves the same purpose effectively.
Origin Session ID
Origin Session ID: 88a6ed3a-b1b9-461a-aaf3-7c9984bd12e7
Handoff Retrieval Hints
Retrieval Hint: "sync_all dev branch constraint update"
Context
The
sync_allMCP tool currently synchronizes GitHub issues and releases with local Markdown files. However, runningsync_allon a feature branch results in pulling new Markdown files that haven't been merged todevinto the current branch, polluting the feature branch with unrelated documentation commits.The Problem
Running
sync_allinside a feature branch introduces unrelated issue metadata files, making the PR noisy and entangling documentation sync commits with feature code commits. This was empirically observed in a recent PR where unrelated markdown file updates were absorbed into a feature branch becausesync_allwas executed prior to checking outdev.The Architectural Reality
The tool description in
ai/mcp/server/github-workflow/openapi.yamlforsync_alllacks a constraint regarding which branch it should be invoked in. Agents rely heavily on these tool descriptions (the prompt) to understand operational constraints.The Fix
Update the tool description for
sync_allinopenapi.yamlto explicitly state:devbranch. The tool creates and updates local markdown files based on GitHub content; running it on a feature branch will pollute the branch with unrelated documentation commits.Acceptance Criteria
sync_alldescription inopenapi.yamlincludes a bolded constraint to only use it inside thedevbranch.Out of Scope
sync_allinSyncService.mjs(e.g., adding branching logic or preventing execution automatically by reading.git/HEAD). A simple prompt engineering / tool description update suffices for now.Avoided Traps
Origin Session ID
Origin Session ID: 88a6ed3a-b1b9-461a-aaf3-7c9984bd12e7
Handoff Retrieval Hints
Retrieval Hint: "sync_all dev branch constraint update"