Add spec-review skill: independent, multi-model design/spec review#614
Merged
Conversation
Adds a new developer skill under .github/skills/spec-review/ that reviews a design or spec BEFORE any code is written — answering "should we build this, and is the approach right?". It is the pre-code companion to the pr-review skill (which reviews already-written code). The skill fans out parallel sub-agents, each doing its OWN research against the real codebase and ecosystem rather than trusting the spec, across six lean dimensions: necessity-and-scope, approach-and-alternatives, feasibility-vs- reality, risks-unknowns-edge-cases, dx-and-user-impact, and a multi-model cross-check from a different model family (latest Opus / GPT / Gemini, no pinned versions). It emits a decision-oriented recommendation (proceed / proceed-with-changes / reconsider) to stdout and does not write code or edit the spec. Reuses pr-review's proven patterns via its own adapted _shared-contract.md: the Team Lead Test signal-to-noise gate, the no-quota principle (a reasoned "the approach is sound" is a complete result), and the latest-per-family multi-model approach. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
List the new spec-review skill in .github/skills/README.md, directly after the existing pr-review row. Index-only change; the pr-review row is untouched. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
Build Metrics ReportBinary Sizes
Test Results✅ 1545 passed, 1 skipped out of 1546 tests in 424.6s (-61.6s vs. baseline) Test Coverage❌ 18% line coverage, 37.2% branch coverage · CLI Startup Time43ms median (x64, Updated 2026-07-10 22:22:38 UTC · commit |
Reverse the no-execution rule: dimensions now verify load-bearing mechanics with cheap, temp-dir experiments (evidence hierarchy: experiment > authoritative docs > code-read > spec assertion). Add load-bearing-assumption identification and verified/refuted/unproven tagging to feasibility-vs-reality, backward-compat verification framing, cross-model agreement counting (confirmed by N families) as the strongest signal, evidence-based disagreement resolution, and a distinct 'Must prove before ship' report section for unclosed load-bearing assumptions. Examples updated with generic, framework-agnostic content. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
nmetulev
added a commit
that referenced
this pull request
Jul 10, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot stopped reviewing on behalf of
nmetulev due to an error
July 13, 2026 19:08
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a new spec-review GitHub skill for microsoft/winappcli, including a shared output contract and dimension-specific instructions to drive independent, pre-implementation design reviews.
Changes:
- Introduces the
spec-revieworchestrator skill definition and workflow guidance. - Adds dimension guides + a shared output contract to standardize sub-agent outputs.
- Updates the skills README to list and describe the new
spec-reviewskill.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| .github/skills/spec-review/SKILL.md | Defines the spec-review orchestrator skill, workflow, and reporting format. |
| .github/skills/spec-review/dimensions/_shared-contract.md | Establishes a common output contract for all spec-review dimensions. |
| .github/skills/spec-review/dimensions/necessity-and-scope.md | Adds guidance for evaluating mission fit, duplication, and scope. |
| .github/skills/spec-review/dimensions/approach-and-alternatives.md | Adds guidance for validating approach soundness and identifying alternatives. |
| .github/skills/spec-review/dimensions/feasibility-vs-reality.md | Adds guidance for verifying load-bearing assumptions via experiments/docs/code. |
| .github/skills/spec-review/dimensions/risks-unknowns-edge-cases.md | Adds guidance for surfacing concrete risks, edge cases, and failures. |
| .github/skills/spec-review/dimensions/dx-and-user-impact.md | Adds guidance for CLI/API UX consistency, breaking changes, and cross-surface impact. |
| .github/skills/spec-review/dimensions/multi-model.md | Adds instructions for cross-model-family validation and disagreement resolution. |
| .github/skills/README.md | Lists the new spec-review skill alongside existing skills. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+9
to
+11
| Ground risks in reality — a risk worth raising points at a concrete failure mode, | ||
| an actual compat surface, or a specific unknown, not generic "there could be | ||
| bugs." Do your own research into the affected surfaces. |
Comment on lines
+34
to
+40
| - **Service shape** (from the repo's architecture guide): | ||
| | Pattern | When | | ||
| |---------|------| | ||
| | Interface + DI service | stateful, needs deps | | ||
| | Static helper | pure functions | | ||
| | Data document | wraps a file/data format | | ||
| | Partial class | splitting a large tightly-coupled service | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Adds a new developer skill under
.github/skills/spec-review/that reviews a design or spec before any code is written — answering "should we build this, and is the approach right?"This is the pre-code companion to the
pr-reviewskill.pr-reviewreviews code that already exists and deliberately avoids the "should this exist" debate;spec-reviewis the opposite — it evaluates a proposal and makes the necessity + approach questions its whole point.The motivating need: contributors want to validate a design with multiple sub-agents that use different model families (Opus / GPT / Gemini) and, crucially, get their information from their own research against reality — not by blindly trusting the spec. That independent-research + multi-model-family emphasis is the heart of this skill.
How it works
Given a spec (usually a markdown file path) or a described feature, the orchestrator captures it, maps the real codebase areas it touches, establishes model-family diversity, fans out parallel sub-agents, and consolidates into a decision-oriented recommendation on stdout: proceed / proceed-with-changes / reconsider, plus top risks, the single best alternative, open questions to resolve before implementation, and per-dimension coverage. It does not write code or edit the spec.
Dimensions (kept lean — 6, not a sprawling set)
AppxManifestDocument,ManifestHelper, existing services) and ecosystem (SDK tools, Windows App SDK APIs) alternatives with tradeoffs.Reuses pr-review's proven patterns
dimensions/_shared-contract.md(retargeted from "diff" to "spec") keeping the Team Lead Test signal-to-noise gate and the severity/confidence guides.Files
These are hand-written developer skills (not the shipped
winappplugin skills), so there is nothing to auto-generate or build.Opening as draft for review.