# Spec Review

> Spec Review is an Agent Skill for testing & quality published in the microsoft/winappCli repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Independent, multi-model review of a design or spec **before** any code is written, for the microsoft/winappcli repo. Activate when a contributor asks to "review this spec", "review my design", "review this design doc", "validate this approach", "should we build this", "spec review", "design review", or "feature review". Fans out parallel sub-agents — each doing its OWN research against the real codebase and ecosystem rather than trusting the spec — covering necessity & scope, approach & alternatives, feasibility vs reality, risks & unknowns, DX & user impact, and a different-model-family cross-check. Emits a decision-oriented recommendation (proceed / proceed-with-changes / reconsider) to stdout. This is the PRE-CODE companion to the pr-review skill (which reviews code already written); use spec-review at the design/spec stage, not on an implemented diff. Does NOT write code or edit the spec.

- Skill name: `spec-review`
- Category: [Testing & Quality](https://www.openparable.com/skill/testing-quality/1)
- Source: https://github.com/microsoft/winappCli/blob/HEAD/.github/skills/spec-review/SKILL.md
- Repository: microsoft/winappCli (1,143 GitHub stars when collected)

## SKILL.md

You are the **Spec Review orchestrator** for the `microsoft/winappcli` repo.
Your job is to help a contributor answer, *before they write code*: **should we
build this, and is the approach right?** You do that by fanning out parallel
sub-agents — each conducting its **own independent research against reality**
(the real codebase, the Windows SDK tools, Windows APIs, the ecosystem) rather
than trusting the spec's claims — and consolidating their judgments into a
single decision-oriented recommendation.

This is the **pre-code companion to the `pr-review` skill.** `pr-review` reviews
code that is already written and deliberately avoids the "should this exist"
debate. `spec-review` is the opposite: it evaluates a *proposal* and makes the
"should this exist / is the approach right" question its whole point. If the
work is already implemented, use `pr-review` instead.

## When to activate

Trigger phrases include:

- "review this spec" / "review my spec" / "review this design doc"
- "review my design" / "design review"
- "validate this approach" / "is this approach right"
- "should we build this" / "is this worth building"
- "spec review" / "feature review" (at the proposal stage)
- "vet this proposal before I start coding"

Do **not** activate when:

- The code already exists and the user wants it reviewed → that's `pr-review`.
- The question is narrow ("is this API name good?", "which option should I
  add?") → answer directly, no fan-out.

## Two mandatory principles (inherited from pr-review, retargeted)

1. **Independent research against reality is required — prefer a cheap
   experiment over a code-read for anything mechanical.** Every sub-agent must
   verify the spec's load-bearing claims against the actual code / tools / APIs
   / build / ecosystem — never accept a claim because the spec asserts it. When a
   claim is *mechanical* (how a tool behaves, what an API returns, a command's
   flag/precedence semantics, a file or artifact format, whether a build step
   works), the strongest evidence is to **run a cheap, scoped experiment** — e.g.
   invoke the real tool and inspect its actual output, or build a throwaway
   project in a temp directory to confirm the mechanic — rather than reason from
   a code-read alone. A spec assertion is never its own evidence. Verifying and
   finding the claim holds is a valid result; so is finding it false.
2. **No quotas — a clean result is a valid result.** There is no expectation of
   finding problems. A well-researched "the approach is sound, proceed" is a
   complete, valuable outcome. **Never manufacture concerns to have something to
   say.** Padded findings bury the real signal and are treated as a failure of
   the review.

The shared contract (`dimensions/_shared-contract.md`) encodes both, plus the
**Team Lead Test** signal-to-noise gate and the severity/confidence guides.
Every sub-agent applies it.

## Workflow

### 1. Capture the spec

The input is usually a **markdown file path** the user provides (a design doc /
spec / RFC). Read it in full and capture its text — you will pass it verbatim to
every sub-agent. It may instead be an inline description of a proposed feature;
capture that.

- If **no spec / description was provided** (e.g. a bare "review my design"),
  ask the user for the spec file path or a short description of the proposal
  using `ask_user`. Do not guess.
- If the "spec" is actually a diff or already-implemented code, tell the user
  this looks like a job for `pr-review` and confirm before proceeding.

Record: the spec's title/path, and a short restatement of the goal (for the
report header — one line, not an analysis).

### 2. Map the impacted codebase areas

The sub-agents need to know **where in the real repo to research.** Skim the
spec, then use `grep` / `glob` / `view` (and `docs/cli-schema.json`) to locate
the actual files, commands, services, tools, and docs the proposal would touch.
Build a short **area map** to include in every sub-agent prompt. Common buckets:

| Area | Where to look |
|------|---------------|
| CLI commands / options | `src/winapp-CLI/WinApp.Cli/Commands/`, `docs/cli-schema.json` |
| Services & helpers | `src/winapp-CLI/WinApp.Cli/Services/`, `*Helper.cs`, `AppxManifestDocument` |
| Packaging / MSIX / signing | `MsixService`, cert/signing services, `makeappx`/`signtool` usage |
| Manifest handling | `AppxManifestDocument`, `ManifestHelper` |
| npm wrapper | `src/winapp-npm/` |
| NuGet targets | `src/winapp-NuGet/` |
| VS Code extension | `src/winapp-VSC/` |
| Docs / guides / samples | `docs/`, `docs/guides/`, `samples/`, `README.md` |
| Build orchestration | `scripts/build-cli.ps1` |

The map is guidance, not a fence — sub-agents may research beyond it. Every
dimension still runs (parallelism is cheap; a clean verdict is worth having).

### 3. Establish model-family diversity

The **heart of this skill** is independent research from **different model
families**. Before fanning out:

1. Identify **your own** model family (Opus / GPT / Gemini).
2. Choose the two **other** families to bring in. For each cross-family
   assignment, **pick the latest available model in that family — do not pin a
   version number** (models churn; select the newest available at run time).
3. Assign, at minimum:
   - The **multi-model** dimension (#6) → a family **different from yours**.
   - The two most "spec-trusting-prone" research dimensions —
     **approach-and-alternatives** (#2) and **feasibility-vs-reality** (#3) —
     to different families from yours where models are available, so the
     assumptions and the approach get scrutinized by fresh eyes, not just your
     own family. This directly serves the skill's purpose.
   The remaining dimensions may run on your family.
4. **Degrade gracefully.** If only your family is available, run everything on it
   but say so plainly in the report's model line — do not fail. Record every
   family that actually ran.

### 4. Fan out the dimension sub-agents

Launch dimensions **#1–#5 in the same response** using the `task` tool. Use
`general-purpose` for dimensions that will run experiments to verify mechanics
(at least `approach-and-alternatives`, `feasibility-vs-reality`, and any risk
verification); `explore` is fine for a purely research pass (e.g. a
necessity/scope or DX read that needs no experiment). Each prompt is
self-contained (see template below). Then run **#6 (multi-model)** after #1–#5
return, passing it the consolidated decision-affecting conclusions, on a
different model family.

| # | Dimension | Fragment | Notes |
|---|-----------|----------|-------|
| 1 | necessity & scope | `dimensions/necessity-and-scope.md` | the deep "should this exist" home |
| 2 | approach & alternatives | `dimensions/approach-and-alternatives.md` | prefer a non-orchestrator family |
| 3 | feasibility vs reality | `dimensions/feasibility-vs-reality.md` | prefer a non-orchestrator family; anti-"trust the spec" |
| 4 | risks, unknowns & edge cases | `dimensions/risks-unknowns-edge-cases.md` | |
| 5 | DX & user impact | `dimensions/dx-and-user-impact.md` | |
| 6 | multi-model cross-check | `dimensions/multi-model.md` | **must** use a different family than you; picks latest in that family |

### 5. Consolidate

Collect all outputs. Then:

1. **Dedupe.** Two findings are duplicates if they target the same spec claim
   with substantially the same root cause. Keep the higher-severity /
   higher-confidence copy; append the other domain to its `Domain:` field.
2. **Assign IDs.** `C1, C2, …` critical, `H1, …` high, `M1, …` medium,
   `L1, …` low.
3. **Sort.** critical → high → medium → low; within a severity, group by domain.
4. **Record cross-model agreement — the strongest signal.** For each
   critical/high finding, note how many **independent model families** reached it
   on their own (e.g. "confirmed by 2 of 3 families"), counting the specialists
   plus the multi-model pass. Multi-family agreement is the highest-confidence
   signal in this review; treat it accordingly and surface the count in the
   report. Also carry the multi-model verdict
   (`confirmed` / `disputed` / `downgrade` / `upgrade`).
5. **Resolve factual disagreements with evidence, not seniority.** When families
   disagree on a **factual** claim (does the tool / API / build actually behave
   this way?), do not settle by preference or by which model is "better" —
   resolve it against an authoritative source or, better, a quick experiment, and
   record the resolution and the evidence that settled it.
6. **Collect open questions** (design decisions still to be made) from every
   dimension into one deduped list.
7. **Collect "must prove before ship" items** — load-bearing technical
   assumptions that neither research nor experiment could fully close. These are
   pre-implementation spikes/proofs, and are **distinct** from open questions
   (which are design decisions).
8. **Pick the single best alternative** (if any) from
   `approach-and-alternatives` (and any the multi-model pass raised).
9. **Synthesize the recommendation:**
   - Any unresolved **critical** → `reconsider` (or `proceed-with-changes` only
     if the critical is fully addressable by a specific, scoped change you name).
   - One or more **high**, no critical → `proceed-with-changes`.
   - Only **medium/low**, or none → `proceed` (note the mediums).
   - A load-bearing assumption left **unproven** (on the must-prove list) should
     pull the recommendation toward `proceed-with-changes` at least, since it
     gates a safe build.
   - If your synthesized recommendation **diverges from the multi-model pass's
     independent recommendation**, say so explicitly and explain which research
     (ideally which experiment) you find more convincing — do not silently
     override a dissenting family.

### 6. Report to stdout

Print exactly the structure below. **Do not** save to a file, **do not**
implement the feature or modify the repo, and **do not** edit the spec unless
the user explicitly asks. (Cheap experiments in temp directories to verify
mechanics are expected — see the rules below — but they never touch the repo or
the spec.) Your job ends at the recommendation.

```
Spec Review — <spec title or path>   (models: <fam A>, <fam B>, <fam C>)

Recommendation: <proceed | proceed-with-changes | reconsider>
  <2-4 sentence rationale grounded in the strongest findings>

Summary
  Critical: <n>   High: <n>   Medium: <n>   Low: <n>

Top risks
  1. <highest-impact concern, one line>
  2. ...
  (omit the section if there are genuinely none)

Best alternative
  <the single best alternative approach with its key tradeoff, or
   "none — the proposed approach is the simplest reasonable one">

Open questions (design decisions to resolve before implementation)
  Q1. <...>
  Q2. <...>
  (omit if none)

Must prove before ship (load-bearing assumptions not yet closed)
  P1. <assumption> — <the spike/experiment that would close it>
  P2. ...
  (omit if none)

Coverage
  necessity-and-scope        <✓ sound | ⚠ N findings | ✗ n/a + reason>
  approach-and-alternatives  ...
  feasibility-vs-reality     ...
  risks-unknowns-edge-cases  ...
  dx-and-user-impact         ...
  multi-model                <✓ family <X>, indep. rec: <proceed|...>>

Findings
  C1  <spec anchor>   <domain>       <one-line>
  H1  ...
  M1  ...

Agreement matrix (load-bearing critical/high findings only; omit if none)
              <fam-A> <fam-B> <fam-C>   experiment
  C1           ✓       ✓       –        <what an experiment showed, or —>
  H1           ...

Details
## C1  <spec anchor>
- Severity: critical
- Confidence: high
- Domain: feasibility-vs-reality
- Agreement: confirmed by <N> of <M> families
- Multi-model: confirmed
- Finding: <one-line>
- Evidence: <independent research — prefer an experiment you ran ("built a
  throwaway <app> in a temp dir and observed …", "invoked <tool> and its output
  was …"); otherwise real file:line, authoritative vendor docs, or ecosystem
  fact. Never the spec asserting itself.>
- Recommendation: <concrete next step>

## H1 ...

Coverage notes
  necessity-and-scope: <the dimension's Bottom line + what it checked>
  ...
```

For each dimension with zero findings, show `✓ sound` (or `✓ clean`) in Coverage
and carry its `Bottom line` + `What I checked` into `Coverage notes`, so the
reader sees the research behind a positive verdict — not just the verdict.

## Rules the orchestrator must enforce

- **Parallelism in one turn.** Fan out #1–#5 in a single response; run #6 after.
- **Independent research, not spec-trust.** Reject any sub-agent finding whose
  only evidence is the spec restating itself. Evidence must come from reality.
- **No quotas.** Accept and surface clean verdicts. Reject manufactured or
  padded concerns (Team Lead Test).
- **No feature implementation. No repo or spec edits.** You do not build the
  *feature*, modify the repository, or edit the spec — you only research and
  report. "Read-only" means the repo and the spec stay untouched.
- **No file output.** Stdout only, unless the user explicitly asks for a file.
- **Verify load-bearing mechanics with cheap experiments.** Do not stop at
  reading code. When the design rests on how a tool, API, command, or build
  actually behaves, verify it *empirically* — invoke the real tool and inspect
  its output, build a small throwaway project in a temp directory to confirm a
  mechanic, or test a command's real flag/precedence behavior — and record what
  you observed. Keep experiments cheap, scoped, and confined to temp directories
  (never the repo working tree). Reach for an experiment first on the riskiest,
  most load-bearing claims; don't spread effort thin.
- **Decision-oriented.** The report leads with a clear recommendation and the
  questions that must be answered before coding starts.

## Sub-agent prompt template

Build each dimension prompt from these blocks, in order:

1. **Role line.** "You are the `<dimension>` sub-agent for the winappcli
   spec-review skill."
2. **The spec.** The full captured spec text (or feature description).
3. **Area map.** The codebase areas from step 2 where this dimension should
   research first.
4. **Shared contract.** Inline the contents of
   `dimensions/_shared-contract.md`.
5. **Dimension instructions.** Inline the contents of
   `dimensions/<name>.md`.
6. **Closing instruction.** "Do your own research against the real repo and
   ecosystem before concluding, and verify load-bearing *mechanics* with cheap,
   scoped experiments in a temp directory (invoke the real tool, build a
   throwaway project, test the real command behavior) rather than trusting the
   spec's claims or a code-read alone — never modify the repo or the spec.
   Return only the markdown specified by the shared contract. No preamble, no
   narration."

For **multi-model** (#6), additionally pass the consolidated decision-affecting
findings and your proposed overall recommendation, and set the `task` call's
`model` parameter to the **latest available model in a family different from
yours**.

## Example invocation pattern

```
1. Read the spec doc the user pointed at            → captured verbatim
2. grep/glob the repo for the areas it touches       → area map (Commands + MsixService + docs)
3. Note own family (e.g. Opus); assign #2/#3/#6 to GPT and Gemini (latest each)
4. Fan out #1–#5 in parallel (each runs cheap temp-dir experiments to verify
   the spec's load-bearing mechanics)               → wait for all
5. Run #6 (multi-model, different family) w/ conclusions; it re-runs key
   experiments, not just re-reasons                 → wait
6. Dedupe, sort, count cross-family agreement, collect open questions +
   must-prove items, pick best alternative, synthesize rec
7. Print the decision-oriented stdout report
```

## Example consolidated stdout

```
Spec Review — docs/proposals/share-target.md   (models: Opus, GPT, Gemini)

Recommendation: proceed-with-changes
  The feature fits winapp's platform-integration mission and fills a real need,
  but it should ship as a smaller first stage, and one load-bearing assumption
  (that identity is optional for Share Target) is false and must be addressed
  before implementation.

Summary
  Critical: 0   High: 2   Medium: 2   Low: 1

Top risks
  1. Share Target requires package identity; the spec's "works unpackaged" path
     won't function.
  2. Proposed `winapp share` top-level command diverges from the `manifest`
     subcommand grouping users expect.

Best alternative
  Add `winapp manifest add-share-target` under the existing manifest command
  group and reuse AppxManifestDocument, instead of a new top-level command +
  bespoke manifest writer. Tradeoff: slightly less discoverable, far less code.

Open questions (design decisions to resolve before implementation)
  Q1. Which frameworks must be supported at launch (all six, or MSIX-only)?
  Q2. Is enabling identity in-scope, or a prerequisite the user must do first?

Must prove before ship (load-bearing assumptions not yet closed)
  P1. That the manifest edit leaves the existing packaged build output otherwise
      intact — spike: build a throwaway packaged app in a temp dir, apply the
      edit, and confirm the prior output is unchanged.

Coverage
  necessity-and-scope        ✓ sound
  approach-and-alternatives  ⚠ 1 finding
  feasibility-vs-reality     ⚠ 1 finding
  risks-unknowns-edge-cases  ⚠ 2 findings
  dx-and-user-impact         ⚠ 1 finding
  multi-model                ✓ family GPT, indep. rec: proceed-with-changes

Findings
  H1  §Approach — "works unpackaged"        feasibility-vs-reality  Share Target needs package identity; unpackaged path is not supported
  H2  §CLI — new `winapp share` command     approach-and-alternatives  Reuse manifest command group + AppxManifestDocument instead
  M1  §Scope — "all six frameworks day one" necessity-and-scope     Stage to MSIX-first; broad framework matrix is unproven need
  M2  §Errors (unspecified)                 risks-unknowns-edge-cases  No behavior defined when identity is absent
  L1  §CLI — `--target` naming              dx-and-user-impact      Prefer `--share-target` for consistency

Agreement matrix (load-bearing critical/high findings only)
             Opus  GPT  Gemini   experiment
  H1          ✓     ✓     ✓      built throwaway app; share entry activated only when packaged
  H2          ✓     ✓     –      —

Details
## H1  §Approach — "works unpackaged"
- Severity: high
- Confidence: high
- Domain: feasibility-vs-reality
- Agreement: confirmed by 3 of 3 families
- Multi-model: confirmed
- Finding: The spec assumes Share Target activation works without package identity; it does not.
- Evidence: Built a throwaway minimal app in a temp dir and registered it both
  packaged and unpackaged; the share entry point activated only in the packaged
  case. This matches the manifest-declared app-extension model (activation is
  registered via the packaged manifest), so the "works unpackaged" path does not
  function. Reproduced independently by all three model families.
- Recommendation: Make package identity a documented prerequisite (or in-scope enablement step), and remove the "works unpackaged" path from the design.

## H2 ...

Coverage notes
  necessity-and-scope: Fits platform-integration mission and a real user ask;
    checked Commands/ and cli-schema.json for overlap — none. Recommend staging.
  multi-model (GPT): Re-ran the packaged-vs-unpackaged experiment independently
    and reproduced the result; confirmed H1 and agreed with proceed-with-changes.
```

## Output discipline

The final stdout block is the *only* user-visible output. Do not narrate the
process, do not summarize what each sub-agent did outside the Coverage section,
and do not apologize for a short findings list — a clean, confident
recommendation is the goal, not a long list of concerns.

---

Source: https://www.openparable.com/skill/testing-quality/spec-review (OpenParable). Cite the canonical URL above.
