Issue Resolution Protocol

Automated 14-step issue resolution with GitHub webhook integration and mission templates.

Issue Resolution Protocol

When a GitHub issue is opened on a mapped repository, VantagePeers automatically creates a mission with 14 tasks following the Issue Resolution Protocol (IRP). The assigned orchestrator works through each step, with progress comments posted back to GitHub.

How It Works

GitHub Issue Opened
       |
       v
Webhook receives event
       |
       v
Auto-comment: "Investigating - assigned to {orchestrator}"
       |
       v
Mission created with 14 tasks (from template)
       |
       v
Orchestrator executes steps T0-T13
       |
       v
Auto-comments at T6, T8, T11
       |
       v
Issue closed with fix deployed

The 14 Steps (T0-T13)

GitHub Auto-Comments

VantagePeers posts 4 comments on the GitHub issue automatically:

1. On open: "Investigating - assigned to {orchestrator}"
2. After T6: "Bug reproduced in test suite. Root cause identified."
3. After T8: "Fix ready. All tests pass including new regression test."
4. After T11: "Fixed and deployed to production. Regression test added."

Customizing the Template

The IRP template is stored in the missionTemplates table and can be modified via MCP tools:

View current template

// get_mission_template
{ "name": "issue-resolution-v2" }

Update steps

// update_mission_template
{
  "name": "issue-resolution-v2",
  "steps": [
    { "title": "Acknowledge", "description": "Auto-posted GitHub comment" },
    { "title": "KB Search", "description": "Search fixPatterns for similar issues" }
  ],
  "createdBy": "carol"
}

You can add, remove, or reorder steps. Changes take effect on the next issue opened.

GitHub Webhook Setup

1. Configure webhook on GitHub

In your repo settings, add a webhook:

• URL: https://your-deployment.convex.site/github/webhook
• Content type: application/json
• Events: Issues, Issue comments, Pull requests, Pull request reviews
• Secret: Match your GITHUB_WEBHOOK_SECRET env var

2. Map repo to orchestrator

// add_repo_mapping
{
  "repo": "your-org/your-repo",
  "orchestrator": "dave",
  "project": "your-project"
}

3. Set environment variables

npx convex env set GITHUB_TOKEN=ghp_your_token
npx convex env set GITHUB_WEBHOOK_SECRET=your_secret

The GITHUB_TOKEN needs repo scope to post comments. The webhook secret validates incoming requests.