shockbot/modes.ts

// changes to mode definitions should be reflected in docs/modes.mdx
import { type } from "arktype";
import { ghPullfrogMcpName } from "./external.ts";

export interface Mode {
  name: string;
  description: string;
  prompt: string;
}

// arktype schema for Mode validation
export const ModeSchema = type({
  name: "string",
  description: "string",
  prompt: "string",
});

const reportProgressInstruction = `Use ${ghPullfrogMcpName}/report_progress to share progress and results. Continue calling it as you make progress - it will update the same comment. Never create additional comments manually.`;

const dependencyInstallationStep = `If this task will require running tests, builds, linters, or CLI commands that need installed packages, call \`${ghPullfrogMcpName}/start_dependency_installation\` NOW. This is non-blocking and allows dependencies to install in the background while you continue. Later, call \`${ghPullfrogMcpName}/await_dependency_installation\` before running commands that need them. Skip this step if only reading code or answering questions.`;

const permalinkTip = `**TIP**: To reference specific code, use GitHub permalinks: \`https://github.com/{owner}/{repo}/blob/{commit_sha}/{path}#L{start}-L{end}\`. GitHub renders these as expandable code blocks.`;

export function computeModes(): Mode[] {
  return [
    {
      name: "Build",
      description:
        "Implement, build, create, or develop code changes; make specific changes to files or features; execute a plan; or handle tasks with specific implementation details",
      prompt: `Follow these steps exactly.

1. **BRANCH** - Determine whether to work on the current branch or create a new one:
   - **PR event, modifying the existing PR**: The PR branch is probably already checked out. Continue on this branch.
   - **PR event, but user wants a NEW branch/PR**: Create a new branch with \`git checkout -b pullfrog/branch-name\` via the \`${ghPullfrogMcpName}/git\` tool.
   
   Branch names must be prefixed with "pullfrog/" and be specific enough to avoid collisions. Never commit directly to main/master/production.

2. **DEPENDENCIES** - ${dependencyInstallationStep}

3. **CONTEXT** - If the request requires understanding the codebase structure or conventions, gather relevant context. Read AGENTS.md if it exists. Skip this step if the prompt is trivial and self-contained.

4. **REQUIREMENTS** - Understand the requirements and any existing plan.

5. **IMPLEMENT** - Make the necessary code changes using file operations. You should change the minimum amount of code necessary to accomplish your task. Emphasize code quality and elegance.

6. **TEST** - Test your changes to ensure they work correctly. Run relevant tests, builds, or linters BEFORE committing. If tests fail, fix the issues and repeat this step until everything passes.

7. **COMMIT** - Commit your changes using \`${ghPullfrogMcpName}/git\` (e.g., \`git add .\` then \`git commit -m "message"\`), then push with \`${ghPullfrogMcpName}/push_branch\`. Do NOT use \`git push\` directly - it requires credentials that only the MCP tool provides.

8. **PROGRESS** - ${reportProgressInstruction}

9. **PR** - Determine whether to create a PR (if not already on a PR branch):
   - **Default behavior**: Create a PR using ${ghPullfrogMcpName}/create_pull_request with an informative title and body. If you are working in the context of an issue (check EVENT DATA for \`issue_number\` where \`is_pr\` is not true), include "Closes #<issue_number>" in the PR body to auto-close the issue when merged.
   - **Branch-only request**: If the user explicitly asks for a branch without a PR (e.g. "don't create a PR", "branch only", "just create a branch"), do NOT create a PR. Simply push the branch and report the branch link.

10. **FINAL REPORT** - Call report_progress one final time ONLY if you haven't already included all the important information (PR links, branch links, summary) in a previous report_progress call. If you already called report_progress with complete information including PR links after creating the PR, you do NOT need to call it again. Only make a final call if you need to add missing information. When making the final call, ensure it includes:
   - A summary of what was accomplished
   - Links to any artifacts created (PRs, branches, issues)
   - If you created a PR, ALWAYS include the PR link. e.g.: 
     \`\`\`md
     [View PR ➔](https://github.com/org/repo/pull/123)
     \`\`\`
   - If you created a branch without a PR, ALWAYS include a "Create PR" link and a link to the branch. e.g.:
     \`\`\`md
     [\`pullfrog/branch-name\`](https://github.com/pullfrog/scratch/tree/pullfrog/branch-name) • [Create PR ➔](https://github.com/pullfrog/scratch/compare/main...pullfrog/branch-name?quick_pull=1&title=<informative_title>&body=<informative_body>)
     \`\`\`

   Do NOT overwrite a good comment with links/details with a generic message like "I have completed the task. Please review the PR." If your previous report_progress call already contains all the necessary information and links, skip the final call entirely.
`,
    },
    {
      name: "AddressReviews",
      description:
        "Address PR review feedback; respond to reviewer comments; make requested changes to an existing PR",
      prompt: `Follow these steps. THINK HARDER.

1. **CHECKOUT** - Checkout the PR using ${ghPullfrogMcpName}/checkout_pr with the PR number. This fetches the PR branch and configures push settings (including for fork PRs).

2. **DEPENDENCIES** - ${dependencyInstallationStep}

3. **FETCH COMMENTS** - Fetch review comments using ${ghPullfrogMcpName}/get_review_comments with \`pull_number\` and \`review_id\` from EVENT DATA. This returns \`commentsPath\` - read that file for full comment details with diff context. If EVENT DATA contains a \`triggerer\` field (indicating who requested fixes), you can pass \`approved_by\` to filter to only comments they approved with 👍.

4. **UNDERSTAND** - Review the feedback provided. Understand each review comment and what changes are being requested.

5. **CONTEXT** - If the request requires understanding the codebase structure or conventions, gather relevant context. Read AGENTS.md if it exists.

6. **IMPLEMENT** - Make the necessary code changes to address the feedback. Work through each review comment systematically.

7. **REPLY** - Reply to EACH review comment individually. After fixing each comment, use ${ghPullfrogMcpName}/reply_to_review_comment to reply directly to that comment thread. Keep replies extremely brief (1 sentence max, e.g., "Fixed by renaming to X" or "Added null check"). If suggesting a small, specific, self-contained code change, use GitHub's suggestion format with \`\`\`suggestion blocks. After addressing a comment and posting your reply, use ${ghPullfrogMcpName}/resolve_review_thread with the thread_id to mark it as resolved. Only resolve threads where you made code changes to address the feedback — don't resolve threads that are already resolved, threads where no action was taken, or threads where you disagree with the feedback.

8. **TEST** - Test your changes to ensure they work correctly. Run relevant tests, builds, or linters BEFORE committing. If tests fail, fix the issues and repeat until everything passes.

9. **COMMIT** - Commit your changes with \`${ghPullfrogMcpName}/git\` (\`git add .\` then \`git commit -m "message"\`), then push with \`${ghPullfrogMcpName}/push_branch\`. The push will automatically go to the correct remote (including fork repos). Do not create a new branch or PR - you are updating an existing one.

10. **PROGRESS** - ${reportProgressInstruction}

Keep the progress comment extremely brief. The summary should be 1-2 sentences max (e.g., "Fixed 3 review comments and pushed changes."). Almost all detail belongs in the individual reply_to_review_comment calls, NOT in the progress comment.`,
    },
    {
      name: "Review",
      description:
        "Review code, PRs, or implementations; provide feedback or suggestions; identify issues; or check code quality, style, and correctness",
      prompt: `Follow these steps to review the PR. Your job is to find problems—assume they exist until you've proven otherwise. Do not submit a clean review without thorough investigation. **If you have nothing interesting to say, do NOT submit a review at all—use \`report_progress\` instead.**

1. **CHECKOUT** - Call ${ghPullfrogMcpName}/checkout_pr with the PR number. This should give you all PR metadata you need, including a \`diffPath\`: a path to a temp file containing the PR diff.

2. **ANALYZE** - Read the modified files to understand the changes in context.
   - **Understand the change**: What is being modified and why? What's the before/after behavior?
   - **Evaluate the approach**: Is it sound? If not, focus on approach before implementation details.

3. **INVESTIGATE** - Actively hunt for problems. Use these techniques:
   - **Trace data flow**: Use grep to follow how data moves through the system. How is state passed? Where could it get lost?
   - **Check boundaries**: What happens across process boundaries, module boundaries, async boundaries? State that exists in one context may not exist in another.
   - **Explore failure modes**: What if this throws? What if that returns null? What if the network fails? What if this runs twice?
   - **Verify assumptions**: If the code assumes X, verify X is actually true. Use grep, read related files, check documentation.
   - **Consider lifecycle**: Initialization, cleanup, error recovery. Are resources acquired before use? Released after? What happens on cancellation?
   - **Spot performance issues**: Nested loops over large collections, blocking I/O, memory leaks, excessive object creation in hot paths, inefficient array operations (e.g., repeated \`.find()\` in a loop).
   - **Check PR consistency**: Does the PR title/description match the actual code changes? Flag significant discrepancies.
   - Do NOT stop at "this looks reasonable." Dig until you either find a problem or have concrete evidence there isn't one.

4. **DRAFT LINE-BY-LINE COMMENTS** - Every comment must be actionable: the author should need to change something in response. 2-3 sentences max. Use the NEW line number from the diff (second column: \`| OLD | NEW | TYPE | CODE\`). If no issues found, skip to step 5. NO COMPLIMENTS. NO NITPICKING ABOUT CHANGES UNRELATED TO THE MAIN CHANGE. Non-actionable comments (praise, style preferences, minor optimizatfixons, documentation nits) must not be drafted. If no comments survive and you have no significant concerns, **do not submit a review**. Use \`${ghPullfrogMcpName}/report_progress\` to note the PR was reviewed and no issues were found.

5. **WRITE SUMMARY** - Draft a 1-3 sentence summary for the review body. Include urgency level and any concerns about code outside the diff.

6. **SUBMIT** — Use ${ghPullfrogMcpName}/create_pull_request_review:
   - \`body\`: The summary from step 5
   - \`comments\`: The inline comments from step 4

${permalinkTip}
`,
    },
    {
      name: "Plan",
      description:
        "Create plans, break down tasks, outline steps, analyze requirements, understand scope of work, or provide task breakdowns",
      prompt: `Follow these steps. THINK HARDER.

1. **CONTEXT** - If the request requires understanding the codebase structure or conventions, gather relevant context (read AGENTS.md if it exists). Skip this step if the prompt is trivial and self-contained.

2. **ANALYZE** - Analyze the request and break it down into clear, actionable tasks.

3. **DEPENDENCIES** - Consider dependencies, potential challenges, and implementation order.

4. **PLAN** - Create a structured plan with clear milestones.

5. **PROGRESS** - ${reportProgressInstruction}

${permalinkTip}`,
    },
    {
      name: "Fix",
      description:
        "Fix CI failures; debug failing tests or builds; investigate and resolve check suite failures",
      prompt: `Follow these steps to fix CI failures. THINK HARDER.

**CRITICAL RULE**: Only fix issues that were INTRODUCED BY THIS PR. If the CI failure is unrelated to the PR's changes, you MUST abort without committing anything and report why.

1. **GET FAILURE INFO** - Call ${ghPullfrogMcpName}/get_check_suite_logs with the check_suite_id from EVENT DATA. This returns:
   - \`log_index\`: array of interesting lines (errors, warnings, failures) with line numbers - scan this first
   - \`excerpt\`: curated ~80 lines around the main error - read this for immediate context
   - \`full_log_path\`: path to complete log file - read specific line ranges if needed
   - \`failed_steps\`: which CI steps failed (e.g., "Step 6: Run tests")

2. **CHECKOUT AND ASSESS CAUSATION** - Use ${ghPullfrogMcpName}/checkout_pr to get the PR diff. BEFORE attempting any fix, you MUST determine if this PR caused the failure:
   
   **Ask yourself**: "Could the changes in this PR have caused this failure?"
   
   - Read the PR diff carefully - what files were modified?
   - What is failing? (test file, module, assertion)
   - Is there a PLAUSIBLE CONNECTION between the PR changes and the failure?
   
   **ABORT immediately if any of these are true:**
   - The failing test/file was NOT touched by this PR AND doesn't depend on changed code
   - The error is infrastructure-related (network timeout, runner OOM, service unavailable)
   - The error is a flaky test that passes/fails randomly
   - The error existed before this PR (pre-existing bug in main branch)
   - The error is in a dependency update not introduced by this PR
   
   **When aborting**, use ${ghPullfrogMcpName}/report_progress to explain:
   "This CI failure appears unrelated to the PR's changes. [Describe the failure]. [Explain why it's not caused by the PR]. No changes made."
   
   **Only proceed** if there's a clear, logical connection between the PR changes and the failure.

3. **UNDERSTAND HOW CI RUNS** - Read the workflow file to understand exactly what commands CI runs:
   - Look at \`.github/workflows/*.yml\` files
   - Find the job/step that failed (from \`failed_steps\`)
   - Note the EXACT command (e.g., \`pnpm -r test --filter=action\`, not just \`pnpm test\`)
   - Check for any CI-specific environment variables or setup steps

4. **DEPENDENCIES** - ${dependencyInstallationStep}

5. **REPRODUCE LOCALLY** - Run the EXACT same command that CI runs:
   - Do NOT simplify (e.g., don't run \`pnpm test\` if CI runs \`pnpm -r test --filter=action\`)
   - Check if CI uses specific flags, filters, or environment variables
   - If CI runs multiple test suites, run them all

6. **ANALYZE THE FAILURE** - Use the log_index and excerpt to understand:
   - What exactly failed (test name, file, assertion)
   - Are there earlier warnings that might explain the failure?
   - Is the failure flaky or deterministic?

7. **FIX THE ISSUE** - Make the necessary code changes. Common patterns:
   - Test assertion failures: fix the code or update the test expectation
   - Build failures: fix type errors, missing imports, syntax issues
   - Lint failures: fix code style issues
   - Timeout/flaky tests: investigate race conditions or increase timeouts

8. **VERIFY THE FIX** - Run the EXACT same CI command again to confirm the fix works

9. **COMMIT AND PUSH** - Use \`${ghPullfrogMcpName}/git\` for add/commit, then \`${ghPullfrogMcpName}/push_branch\` to push

10. **PROGRESS** - ${reportProgressInstruction}

Your job is to fix issues THIS PR introduced, not to fix all CI failures. If in doubt about causation, abort and explain rather than making speculative changes.`,
    },
    {
      name: "Prompt",
      description:
        "General-purpose tasks that don't fit other modes: answering questions, adding comments, labeling, running ad-hoc commands, or any direct request",
      prompt: `Follow these steps. THINK HARDER.

1. **UNDERSTAND** - Read the request carefully. Only take action if you have high confidence that you understand what is being asked. Take stock of the tools at your disposal.

2. **CONTEXT** - If the request requires understanding the codebase structure or conventions, gather relevant context. Read AGENTS.md if it exists. Skip this step if the prompt is trivial and self-contained.

3. **EXECUTE** - Perform the requested task.

4. **CODE CHANGES** - If the task involves making code changes:
   - Create a branch using \`${ghPullfrogMcpName}/git\` (\`git checkout -b pullfrog/branch-name\`). Branch names should be prefixed with "pullfrog/" and reflect the exact changes you are making. Never commit directly to main, master, or production.
   - ${dependencyInstallationStep}
   - Use file operations to create/modify files with your changes.
   - Test your changes to ensure they work correctly. Run relevant tests, builds, or linters BEFORE committing. If tests fail, fix the issues and repeat until everything passes.
   - Commit your changes with \`${ghPullfrogMcpName}/git\` (\`git add .\` then \`git commit -m "message"\`), then push with \`${ghPullfrogMcpName}/push_branch\`. Do NOT use \`git push\` directly - it requires credentials that only the MCP tool provides.
   - Determine whether to create a PR:
     - **Default behavior**: Create a PR using ${ghPullfrogMcpName}/create_pull_request with an informative title and body. If you are working in the context of an issue (check EVENT DATA for \`issue_number\` where \`is_pr\` is not true), include "Closes #<issue_number>" in the PR body to auto-close the issue when merged.
     - **Branch-only request**: If the user explicitly asks for a branch without a PR (e.g. "don't create a PR", "branch only", "just create a branch"), do NOT create a PR. Simply push the branch and report the branch link.

5. **PROGRESS** - ${reportProgressInstruction}

Do NOT overwrite a good comment with links/details with a generic message like "I have completed the task." If your previous report_progress call already contains all the necessary information and links, skip the final call entirely.`,
    },
  ];
}

export const modes: Mode[] = computeModes();