Catalogue › Copilot Code › code-solution-brief

Code solution brief

Writes the solution brief that frames an AI-assisted software build - outcome, users, scope and exclusions, data and systems touched, constraints and non-functional needs, acceptance criteria, owners and route to production - so the coding agent and reviewers work to one agreed definition. Use when a Copilot Code build has been approved, when a prototype is being promoted, or when a build is drifting because nobody wrote down what it is for.

Department

Copilot Code

Lifecycle

Envision, Deliver

Maturity

builder, scaler, ai-enterprise

Risk tiers

1, 2, 3, 4

Platforms

copilot-code, github, azure, power-platform

Editions

starter, scale, enterprise

Reviewers

design-authority, security-privacy

Status

draft

Copilot Cowork

Copilot Code plugin for Copilot Cowork, or this skill on its own: Download SKILL.md

Licence

CC BY 4.0, by Simon Foote

Purpose

An AI coding agent will build something from almost any request, quickly and with confidence. That makes the brief more important, not less: without an agreed outcome, scope, constraints and acceptance criteria, the agent fills the gaps with plausible assumptions, and the team discovers them in review or in production. This skill writes a short, specific solution brief that business owner, engineers, the coding agent and reviewers all work from. Builds go wrong here when the brief is a feature wish-list with no exclusions, no data boundaries and no named owner.

When to use

• A build has been approved through copilot-code:code-use-case-assessment.
• A prototype is being considered for promotion to something people will rely on.
• A build in progress is drifting and nobody can say what is in or out of scope.
• A reviewer asks for the document that defines what the software is meant to do.

When not to use

• Deciding whether to build with Copilot Code at all - use copilot-code:code-use-case-assessment.
• Breaking the brief into work items and acceptance tests - use copilot-code:requirements-to-build.
• Giving the coding agent repository conventions and constraints - use copilot-code:repository-context.
• Setting non-functional requirements patterns across AI solutions - use ai-architecture:ai-non-functional-requirements.
• Briefing a reusable agent rather than an application - use m365-agents:agent-use-case-design.

Questions to ask first

1. What outcome does the software deliver, for which users, and how will the business owner know it works?
2. What is explicitly out of scope, including tempting features that would change the risk or the effort?
3. Which data and systems will it read, write or send to, and under whose identity?
4. What constraints apply: hosting, approved languages and frameworks, accessibility, performance, availability, retention?
5. Who are the business owner, engineering owner and support route, and have they agreed?
6. Is this a prototype with an end date or a production build, and what is the route to production?

Required inputs

• The code use-case verdict and ownership answers from copilot-code:code-use-case-assessment.
• The risk tier from opportunity-management:risk-classification.
• The organisation's engineering standards, approved stacks and hosting options.
• Examples of the current workaround (spreadsheets, forms, reports), cleaned of personal data.

Where an input is missing, mark it [To confirm] in the brief and keep the brief in draft. Never name an owner who has not agreed, and never assume a hosting route or framework is approved.

Decision framework

The brief is ready for build when each section passes.

Practitioner approach

Write the outcome first, in the business owner's words, with a measure: "Site managers record safety inspections on a tablet and the weekly compliance report is produced automatically, so the report is on time and nobody re-keys data." Everything else in the brief serves that sentence. If the owner cannot agree a single outcome, the build is two builds or not yet ready.

Write exclusions with the same care as scope. Coding agents are generous: asked for a form, they will add authentication, exports and dashboards. Each addition expands the security surface and the maintenance burden. List what the software will not do, and why, so that reviewers can push back on scope creep that arrives in a pull request.

Name every data set and system, with direction and identity. "Reads inspection templates from a SharePoint list using the signed-in user's identity; writes completed inspections to the same list; sends a weekly summary email from a service account" is reviewable. "Integrates with SharePoint" is not. This section drives the security review and is where most risk is found or missed.

State constraints the agent must not decide for itself. Approved languages, frameworks and hosting; accessibility requirements; data retention; logging; secrets handling; and anything the organisation forbids, such as storing personal data outside approved locations. Unstated constraints are filled with the agent's defaults, which are rarely the organisation's standards.

Write acceptance criteria as testable statements. "An inspection saved offline uploads when the device reconnects, with no duplicate record" can be tested; "works offline" cannot. Include negative criteria: what must not be possible, such as a site manager seeing another site's inspections. These criteria become the backbone of copilot-code:requirements-to-build and copilot-code:application-validation.

Agree ownership and route in writing. Name the business owner, engineering owner and support route, and state whether this is a prototype with an end date or a production build with environments, reviews and a deployment path. A brief that leaves this open allows a prototype to become production by stealth.

Keep the brief short, versioned in the repository alongside the code, and updated when scope changes. Walk the business owner through it before build starts; a brief they cannot explain back is not finished.

Outputs

• A solution brief on the code-solution-brief template: outcome, users, scope and exclusions, data and systems, constraints, acceptance criteria, ownership, route and risk tier.
• An initial list of acceptance criteria, including negative criteria, for copilot-code:requirements-to-build.
• Open questions and preconditions, each with an owner and a date.

Microsoft platform considerations

Record the intended hosting and integration route (for example Azure services, Power Platform, Microsoft 365 data through approved APIs) and the identity approach, and confirm current options and limits from the relevant source records before the brief is agreed. Repositories, pipelines and hosting must sit under organisational control. Licensing questions go to the Microsoft licensing guide or a licensing partner.

Adoption considerations

Involve two or three intended users in writing the outcome and acceptance criteria; they will test it later and tell colleagues whether it is worth using. Note how users will learn about and be supported in the new tool.

Knowledge considerations

Not applicable as a primary concern, because the brief defines software rather than knowledge; where the software surfaces documents or reference content, name the source and its owner in the data section.

Security and privacy considerations

The data and systems section is the input to copilot-code:generated-code-security-review. Record personal data, external endpoints, write access to systems of record and any service identities. From risk tier 2, share the brief with the security-privacy reviewer before build.

Responsible AI considerations

If the software uses AI features at run time or supports decisions about people, record that in scope and route to the responsible-ai department through risk classification. State how users will know when content is AI-generated.

Evaluation requirements

The acceptance criteria are the evaluation standard for copilot-code:application-validation. Where the software includes AI features at run time, add quality criteria for those features and route them to ai-engineering:ai-solution-testing.

Value measures

Record the baseline from the current workaround and the measure the business owner will use, with source and review date. Include the expected ongoing ownership effort so value is judged net of it. Measure at team or role level.

Scale notes

Starter

Two pages is enough: outcome, users, scope and exclusions, data and systems, five to ten acceptance criteria, owners and route. A partner may help with constraints.

Scale

Use the full template for every production build through the CoE or engineering intake, stored in the repository, and check it against engineering standards before build.

Enterprise

Business-unit engineering teams write briefs on the shared template; briefs at risk tier 2 and above are reviewed by design authority and security before build, and tracked in the engineering portfolio.

Hand-offs

• To copilot-code:requirements-to-build with scope and acceptance criteria.
• To copilot-code:repository-context with constraints and standards.
• To copilot-code:generated-code-security-review with the data and systems section.
• To copilot-code:ai-assisted-prototyping where the route is prototype only.

Reviewer gates

From risk tier 2, design-authority reviews the brief through design-authority:ai-design-review for route, architecture and supportability, and security-privacy reviews data, systems and identities. Findings are blocking or advisory; build does not start with an open blocking finding.

Failure modes

• No exclusions are written, and the coding agent adds features that widen the security surface.
• Data and systems are described vaguely, so the security review misses a write path to a system of record.
• Acceptance criteria are untestable, so validation becomes a demonstration.
• The route is left open, and a prototype becomes production without the gates.

Sources

references/sources.md in this skill lists the source records behind this skill, what each is authoritative for, how volatile it is and what you may do with it. Product availability, licensing, limits and preview status change often, so check the current source before stating them, and cite what you used.

Never

• Start a production build without agreed acceptance criteria and named owners.
• Leave hosting, stack or data handling for the coding agent to decide.
• Include real personal data in examples attached to the brief.
• State licensing conclusions; route them to the Microsoft licensing guide or a licensing partner.