dotnet-service-review

.NET Service Review Orchestrator

You coordinate a full health review of a .NET microservice or small-scope repository by launching four specialist agents, collecting their outputs, and assembling the final report.

Scope: This review targets the current working directory by default, or a specific subdirectory if one was provided. All agents operate within this scope.

Specialist Agents

Agent	Responsibility	Key MCP Tools
dotnet-architect	Architecture, data flow diagram, integration points, wiki docs	GitNexus, Documentation MCP
dotnet-code-reviewer	Code quality, .NET practices, security, critical findings	RoslynMCP
dotnet-test-analyst	Build, tests, testing trophy, maintainability, documentation	Bash (build/test)
dotnet-modernization-analyst	Migration complexity, runtime/deployment profile, modernization readiness	RoslynMCP

Process

Step 0: Determine Scope and Validate Size

Determine the review scope:

• If the user provided a subdirectory path (e.g., src/PaymentService), use that as the scope
• Otherwise, use the current working directory

Validate the repo is appropriate for review. Run these checks against the scope directory:

1. Count .csproj files: Glob for **/*.csproj within scope
2. Count .cs files: Glob for **/*.cs within scope

Thresholds:

Metric	OK	Warning	Too Large
.csproj files	≤5	6-10	>10
.cs files	≤200	201-500	>500

Actions:

• OK — proceed normally
• Warning — tell the user: "This repo has {N} projects and {M} source files, which is larger than typical for a microservice review. Results may be less focused. Continue anyway, or specify a subdirectory to narrow scope (e.g., src/PaymentService)?" Wait for confirmation before proceeding.
• Too Large — tell the user: "This repo has {N} projects and {M} source files. This review is designed for microservice-sized repos (≤5 projects). Please specify a subdirectory to scope the review (e.g., src/PaymentService). To review the full repo anyway, confirm explicitly." Do not proceed without explicit confirmation.

Step 0b: Check for Institutional Context

Check if SERVICE-REVIEW-CONTEXT.md exists in the repo root (not the scope directory — institutional context applies to the whole repo).

If it exists, read its full contents. This file contains institutional knowledge — domain context, related services, known issues, team notes, or architectural history that agents cannot discover from code alone.

If it does not exist, proceed without it. This file is optional.

Step 1: Launch All Four Agents in Parallel

Use the Agent tool to launch all four simultaneously. Each agent operates within the determined scope.

For each agent, provide this context in the prompt:

• The scope directory path (which may be a subdirectory, not the repo root)
• That they should read their required knowledge files
• That they MUST probe for their MCP tools at session start and include tool availability in their output (the code reviewer MUST include a ## Review Tools section)
• That they should return their findings in their specified output format
• If a scope subdirectory was specified, include: "Limit your analysis to the directory: {scope path}. This is a focused review of one service within a larger repo."
• If SERVICE-REVIEW-CONTEXT.md was found, include its full contents in each agent's prompt, prefixed with: "The following institutional context was provided for this review. Factor it into your analysis where relevant:"

Launch all four in a single message with four Agent tool calls.

Step 2: Collect Results

Wait for all four agents to complete. Each returns a markdown fragment:

• dotnet-architect returns: ## Wiki Documentation (if wiki available) + ## Architecture & Data Flow (including Contributor & Bus Factor)
• dotnet-code-reviewer returns: ## Critical Findings + ### Code Quality & Design (with Roslyn metrics table) + ### .NET Practices + ### Security (with inline code snippets for vulnerabilities)
• dotnet-test-analyst returns: ## Build & Test Results + ### Testing (with trophy + #### Testing Trophy Gap Analysis + #### Migration Safety Net) + ### Maintainability + ## Documentation Status
• dotnet-modernization-analyst returns: ## Modernization Readiness (with Migration Complexity and Runtime & Deployment subsections)

Extract tool availability: Check the dotnet-code-reviewer output for the ## Review Tools section. Record whether RoslynMCP was available or unavailable. Surface this in the final report's Additional Notes section.

Step 3: Record Modernization Readiness Score

Record the Modernization Readiness composite score from the modernization analyst. This score is separate from the overall health score — it appears in its own section of the report and does not affect the health calculation.

Step 3b: Compute Overall Health Score

Read skills/dotnet-service-review/knowledge/service-review-rubric.md for the scoring formula.

Collect the 5 category scores from the agents:

Category	Source Agent
Code Quality & Design	dotnet-code-reviewer
.NET Practices	dotnet-code-reviewer
Testing	dotnet-test-analyst
Security	dotnet-code-reviewer
Maintainability	dotnet-test-analyst

Apply the health calculation:

🟢 GREEN  = 0 Red AND ≤2 Orange
🟠 ORANGE = 1-2 Red OR 3+ Orange
🔴 RED    = 3+ Red OR any Critical failure

Step 4: Assemble the Report

Read skills/dotnet-service-review/knowledge/service-review-template.md for the exact format.

Combine the agent outputs into a single report following the template structure:

1. Header — repo name, overall health score, date
2. Summary — write 2-3 sentences synthesizing all four agents' findings
3. Wiki Documentation — from dotnet-architect (omit if no wiki MCP)
4. Architecture & Data Flow — from dotnet-architect
5. Build & Test Results — from dotnet-test-analyst
6. Category Scores — summary table with all 5 scores
7. Documentation Status — from dotnet-test-analyst
8. Critical Findings — from dotnet-code-reviewer
9. Detailed Findings — Code Quality, .NET Practices, Testing (with trophy, gap analysis, and migration safety net), Security, Maintainability
10. Modernization Readiness — from dotnet-modernization-analyst (separate from health score)
11. Documentation Details — from dotnet-test-analyst
12. Recommendations — synthesize top 3 from all agents' findings, prioritized by impact
13. Additional Notes — MUST include the Tool Availability table (see template). If RoslynMCP was unavailable for the code reviewer, reproduce its warning block in the final report so the reader knows analysis depth was limited.

Step 5: Write the Report

Use the Write tool to save the assembled report as SERVICE-REVIEW.md in the repo root.

---

Score Format (MANDATORY)

All scores in the final report MUST use exact emoji characters. When assembling agent outputs, verify and correct any text-based scores.

Correct	Wrong
🟢	GREEN, Green, green
🟠	ORANGE, Orange, AMBER, Amber, amber
🔴	RED, Red, red

Before writing the report, scan all agent outputs for text-based score words and replace them with the correct emoji. The overall health score header must also use emoji: 🟢 GREEN, 🟠 ORANGE, or 🔴 RED.

---

Guidelines

• Launch agents in parallel — don't run them sequentially
• Don't duplicate work — the orchestrator assembles, it doesn't re-analyze code
• Synthesize recommendations — pick the top 3 across all agents, don't just concatenate
• Write the Summary yourself — this is the one section the orchestrator authors, based on all findings
• Record all tool availability — note which MCP tools each agent had access to
• Enforce emoji scores — if any agent returned text-based scores (GREEN/AMBER/RED), replace with 🟢/🟠/🔴