investigation-mode

GitHub Copilot gets significantly more useful when you make its “defaults” explicit: what quality bars to follow, when to stop and investigate, and how to keep edits scoped.

This repo packages those defaults in a form that’s easy to version, review, and reuse.

• Instruction system under .github/instructions/ (rules, workflow, quality gates, execution protocol)
• Reusable prompts under .github/prompts/ (ex: generate a README, generate AGENTS.md, repo story time, create release notes)
• Custom agents under .github/agents/ (ex: Critical Thinking, Mentor, Janitor)
• Agent "skills" playbooks under .github/skills/ (investigation mode, root-cause tracing, verification gates, uncertainty verification, minimalist development, task direction approval)
• VS Code workspace settings under .vscode/settings.json (enables Copilot agent features, advanced reasoning, MCP integration)
• MCP configuration under .vscode/mcp.json (Sequential Thinking, Context7, Memory, Serena)

For a fast setup walkthrough, see QuickStart.md.

Use this repo as a template

1. Copy these folders into your target repository:

- .github/

- .vscode/

1. Review and tailor the instruction files:

- Start with .github/copilot-instructions.md

- Then adjust rules in .github/instructions/ to match your team’s tolerance for “guard rails”.

> [!IMPORTANT]

> The instruction set in .github/instructions/ is designed to reduce flakiness and “agent drift”, but it can also feel strict.

> If you don’t want delegation-heavy workflows or you’re not using subagents, loosen or remove those constraints.

Use it in VS Code

• Open the repository (or your repo that copied these files) in VS Code.
• Ensure GitHub Copilot is enabled.
• Keep .vscode/settings.json checked in so the workspace defaults travel with the repo.

Agent skills are optional playbooks that can be loaded on-demand to handle specific scenarios. Load a skill when you need specialized handling for complex tasks.

Located in .github/skills/, this repo includes 6 ready-to-use skills:

| Skill | Purpose | When to use |

|-------|---------|------------|

| investigation-mode | Pause implementation after 2+ consecutive failures and switch to root-cause analysis before resuming | Repeated test failures or validation errors |

| root-cause-tracing | Trace bugs backward through call stacks to find the original trigger, not just the symptom | Deep debugging of complex issues |

| task-direction-approval | Explain failure root cause, present 2-3 solution options with trade-offs, and wait for explicit user choice | Before switching tech stacks or architectures |

| uncertainty-verification | Verify exact commands, configuration keys, API details, and version-specific behavior via official docs—no assumptions | When providing version-dependent or time-sensitive guidance |

| verification-before-completion | Run verification commands and confirm output before making any completion claims | Before marking tasks as complete or fixed |

| minimalist-surgical-development | Prioritize the smallest diff first, prefer standard libraries, avoid unsolicited refactoring | Code changes and refactoring work |

Vendored obra skills

The full obra/superpowers skill library is vendo