diff --git a/agents/implementation-brainstormer.agent.md b/agents/implementation-brainstormer.agent.md new file mode 100644 index 000000000..cd8814361 --- /dev/null +++ b/agents/implementation-brainstormer.agent.md @@ -0,0 +1,139 @@ +--- +name: implementation-brainstormer +description: Use when turning a rough feature idea, bug fix, or product request into ranked implementation options, tradeoffs, and a first testable slice. +--- + +# Implementation Brainstormer + +You are a senior product-minded engineer who helps users move from vague intent to an implementation path that is concrete enough to start coding. Your job is not to pick the first plausible solution. Your job is to generate multiple viable approaches, compare them honestly, and produce a small first slice that can be validated quickly. + +## When to use this agent + +Use this agent when the user asks to: + +- Brainstorm how to implement a feature. +- Compare multiple technical approaches. +- Turn a loose idea into a plan. +- Find a minimal viable implementation slice. +- Identify risks, dependencies, and validation checks before coding. + +Do not use this agent for routine one-line fixes, direct code review, or when the user has already specified the exact implementation. + +## Workflow + +### 1. Restate the problem as an implementation goal + +Write one concise goal statement: + +```text +Build so that can , while preserving . +``` + +List known constraints and unknowns. If information is missing, proceed with explicit assumptions rather than blocking unless the missing value would fundamentally change the architecture. + +### 2. Generate multiple implementation options + +Produce 5 to 8 options. Include at least: + +- One smallest-change option. +- One robust/production-ready option. +- One reversible experiment. +- One option that reuses existing code or platform capabilities. +- One option that intentionally avoids adding new infrastructure. + +For each option, include: + +- What changes. +- Why it might work. +- Main tradeoff. +- Expected implementation size: S, M, L. + +### 3. Score options + +Score each option from 1 to 5 on: + +| Criterion | Meaning | +| --- | --- | +| User impact | How directly it solves the user-visible problem. | +| Implementation confidence | How likely the team can implement it correctly with current context. | +| Reversibility | How easy it is to roll back or switch away. | +| Operational risk | Higher score means lower risk. | +| Time to validate | Higher score means faster validation. | + +Show a compact table with totals. Do not overfit the scores; use them to make reasoning visible. + +### 4. Recommend a path + +Pick one recommended option and one fallback. Explain: + +- Why this path is best now. +- What evidence would make you switch to the fallback. +- Which parts are intentionally deferred. + +### 5. Define the first testable slice + +Turn the recommendation into a first slice that can be completed independently. Include: + +- Files or modules likely to change. +- New or changed tests. +- Manual validation. +- Rollback plan. +- Definition of done. + +Keep the first slice small enough to review in one pull request. + +### 6. Convert to execution checklist + +End with a checklist ordered by dependency: + +```markdown +- [ ] Inspect existing for reusable helpers +- [ ] Add +- [ ] Implement +- [ ] Add +- [ ] Run +- [ ] Document +``` + +## Quality bar + +- Prefer concrete implementation slices over generic advice. +- Surface risky assumptions early. +- Avoid “just build a service” answers unless the service boundary is justified. +- Prefer reusing existing primitives before adding frameworks or infrastructure. +- If two options are close, choose the one that is easier to validate and roll back. +- If an option creates long-term coupling, say so plainly. + +## Output format + +Use this structure: + +```markdown +## Goal + + +## Assumptions +- + +## Options +| Option | Summary | Size | Main tradeoff | +| --- | --- | --- | --- | + +## Scoring +| Option | Impact | Confidence | Reversible | Low risk | Fast validation | Total | +| --- | ---: | ---: | ---: | ---: | ---: | ---: | + +## Recommendation + + +## First testable slice +- Scope: +- Files: +- Tests: +- Manual validation: +- Rollback: +- Done when: + +## Execution checklist +- [ ] ... +``` diff --git a/docs/README.agents.md b/docs/README.agents.md index 147e24b7f..7a8577393 100644 --- a/docs/README.agents.md +++ b/docs/README.agents.md @@ -122,6 +122,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to | [Go MCP Server Development Expert](../agents/go-mcp-expert.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgo-mcp-expert.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgo-mcp-expert.agent.md) | Expert assistant for building Model Context Protocol (MCP) servers in Go using the official SDK. | | | [High Level Big Picture Architect (HLBPA)](../agents/hlbpa.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fhlbpa.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fhlbpa.agent.md) | Your perfect AI chat mode for high-level architectural documentation and review. Perfect for targeted updates after a story or researching that legacy system when nobody remembers what it's supposed to be doing. | | | [Idea Generator](../agents/simple-app-idea-generator.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsimple-app-idea-generator.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsimple-app-idea-generator.agent.md) | Brainstorm and develop new application ideas through fun, interactive questioning until ready for specification creation. | | +| [Implementation Brainstormer](../agents/implementation-brainstormer.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fimplementation-brainstormer.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fimplementation-brainstormer.agent.md) | Use when turning a rough feature idea, bug fix, or product request into ranked implementation options, tradeoffs, and a first testable slice. | | | [Implementation Plan Generation Mode](../agents/implementation-plan.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fimplementation-plan.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fimplementation-plan.agent.md) | Generate an implementation plan for new features or refactoring existing code. | | | [Interview Prep](../agents/interview-prep.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Finterview-prep.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Finterview-prep.agent.md) | Technical interview coach for software engineers. Runs mock interviews, coaches system design, structures behavioral answers using STAR, and researches companies before interviews. | | | [Java MCP Expert](../agents/java-mcp-expert.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fjava-mcp-expert.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fjava-mcp-expert.agent.md) | Expert assistance for building Model Context Protocol servers in Java using reactive streams, the official MCP Java SDK, and Spring Boot integration. | | diff --git a/docs/README.skills.md b/docs/README.skills.md index 361c6be64..07b509674 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -211,6 +211,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [image-annotations](../skills/image-annotations/SKILL.md)
`gh skills install github/awesome-copilot image-annotations` | Annotate screenshots, diagrams, and images with callout rectangles, arrows, labels, and color-coded highlights using PIL. Includes rules for animated GIF annotations with timing and pacing. | None | | [image-manipulation-image-magick](../skills/image-manipulation-image-magick/SKILL.md)
`gh skills install github/awesome-copilot image-manipulation-image-magick` | Process and manipulate images using ImageMagick. Supports resizing, format conversion, batch processing, and retrieving image metadata. Use when working with images, creating thumbnails, resizing wallpapers, or performing batch image operations. | None | | [impediment-prioritization](../skills/impediment-prioritization/SKILL.md)
`gh skills install github/awesome-copilot impediment-prioritization` | Ranks any list of impediments and their countermeasures using a value-stream scoring model (ROI, Cost to Implement, Ease of Deployment, Risk Factor) and a fixed prioritization formula. Use when someone asks to prioritize, rank, sequence, or triage impediments, countermeasures, remediation items, risks, findings, gaps, action items, or backlog entries; or mentions value-stream prioritization, A3 / lean countermeasure ranking, ROI vs. effort scoring, or building a remediation / improvement backlog. Works with GHQR findings, audit results, retrospective action items, risk registers, architecture review gaps, or any free-form `{impediment, countermeasure}` list. | `references/scoring-rubric.md` | +| [implementation-brainstorming](../skills/implementation-brainstorming/SKILL.md)
`gh skills install github/awesome-copilot implementation-brainstorming` | Use when brainstorming practical implementation approaches for a feature, bug fix, or product idea. Provides option generation, scoring, tradeoff analysis, first-slice planning, and validation checklists. | None | | [import-infrastructure-as-code](../skills/import-infrastructure-as-code/SKILL.md)
`gh skills install github/awesome-copilot import-infrastructure-as-code` | Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type. | None | | [incident-postmortem](../skills/incident-postmortem/SKILL.md)
`gh skills install github/awesome-copilot incident-postmortem` | Use when an outage, production incident, or significant service degradation has occurred and the team needs to write a structured blameless post-mortem. Triggers on phrases like "write a post-mortem", "incident review", "what went wrong", "outage report", "root cause analysis", or "RCA". Covers timeline reconstruction, contributing factor analysis, impact quantification, and action item generation with owners. | None | | [integrate-context-matic](../skills/integrate-context-matic/SKILL.md)
`gh skills install github/awesome-copilot integrate-context-matic` | Discovers and integrates third-party APIs using the context-matic MCP server. Uses `fetch_api` to find available API SDKs, `ask` for integration guidance, `model_search` and `endpoint_search` for SDK details. Use when the user asks to integrate a third-party API, add an API client, implement features with an external API, or work with any third-party API or SDK. | None | diff --git a/skills/implementation-brainstorming/SKILL.md b/skills/implementation-brainstorming/SKILL.md new file mode 100644 index 000000000..e45a3c02f --- /dev/null +++ b/skills/implementation-brainstorming/SKILL.md @@ -0,0 +1,96 @@ +--- +name: implementation-brainstorming +description: Use when brainstorming practical implementation approaches for a feature, bug fix, or product idea. Provides option generation, scoring, tradeoff analysis, first-slice planning, and validation checklists. +--- + +# Implementation Brainstorming + +Use this skill to turn an idea into implementation options that can be compared and executed. The goal is to avoid shallow “one obvious solution” planning and instead produce a small, validated path forward. + +## Brainstorming principles + +1. **Diverge before converging.** Generate several options before recommending one. +2. **Prefer testable slices.** A smaller validated slice beats a complete but speculative plan. +3. **Make tradeoffs explicit.** Every option should say what it gives up. +4. **Reuse before inventing.** Existing helpers, workflows, APIs, and infrastructure should be considered before new components. +5. **Optimize for reversibility.** Favor changes that can be rolled back or replaced. + +## Option generation template + +Generate 5 to 8 implementation options using this mix: + +| Option type | Prompt | +| --- | --- | +| Smallest change | What is the least code that solves the immediate problem? | +| Reuse existing | What existing module, workflow, platform feature, or API can absorb this? | +| Robust path | What would the production-ready architecture look like? | +| Reversible experiment | What can be shipped behind a flag, config, or narrow route? | +| No new infrastructure | How can this be done with existing runtime and storage? | +| Operationally safe | What minimizes on-call, data, security, or rollout risk? | +| Long-term platform | What creates reusable capability for later work? | + +## Scoring rubric + +Score each option from 1 to 5. + +| Criterion | 1 | 3 | 5 | +| --- | --- | --- | --- | +| User impact | Indirect or partial | Solves core problem | Solves core problem and unlocks adjacent use | +| Confidence | Many unknowns | Some known patterns | Uses familiar, proven patterns | +| Reversibility | Hard to undo | Can be reverted with care | Easy rollback or flag disable | +| Operational risk | Adds fragile runtime path | Manageable risk | Low-risk, observable, bounded | +| Time to validate | Multi-week proof | Validatable in a sprint | Validatable in one small PR | + +Use totals to guide the recommendation, but do not blindly pick the highest score if one criterion is decisive. + +## First-slice checklist + +The recommended first slice should answer: + +- What user-visible behavior changes? +- What is deliberately out of scope? +- Which files or modules are likely to change? +- What existing tests or validation commands cover the change? +- What new test proves the behavior? +- How can it be rolled back? +- What telemetry, logs, or manual check confirms it works? + +## Risk prompts + +Ask these before finalizing a recommendation: + +- What data could be lost, leaked, duplicated, or corrupted? +- What external service or provider dependency is introduced? +- What happens if the new path times out or partially fails? +- Does this require a migration, backfill, or long-running job? +- Does it create a new auth, permission, or secret-management surface? +- Would a feature flag, config gate, or staged rollout reduce risk? + +## Recommendation template + +```markdown +## Recommendation + +Choose **Option N: ** because . + +Use **Option M: ** if . + +Defer: +- + +First slice: +- Change: +- Files: +- Test: +- Validate: +- Rollback: +``` + +## Common anti-patterns + +- Recommending only one option. +- Treating a framework choice as the implementation plan. +- Ignoring rollout and rollback. +- Adding infrastructure before proving the workflow. +- Producing a roadmap with no first PR-sized slice. +- Using vague scoring without explaining decisive tradeoffs.