---
name: review-staged
description: Generate structured code review for staged files (git staged changes) using Claude Code agents. Provides feedback before committing to catch issues early.
allowed-tools: Bash(git:*), Bash(dotnet:*), Bash(cd:*), Read, Write
---

# Review Staged Files Skill

Generate AI-powered code review comments for your staged files (git staged changes) before committing. Catch issues early in the development process using the same rigorous review standards as PR reviews.

## Usage

```bash
/review-staged              # Review all staged files
/review-staged --verbose    # Show detailed analysis
```

Examples:
- `/review-staged` - Review all currently staged files
- `/review-staged --verbose` - Show detailed analysis with full context

## What this skill does

1. **Checks for staged files** using `git diff --staged --name-only`
2. **Fetches staged changes** using `git diff --staged`
3. **Performs architectural review**: Questions design decisions, checks for scope creep, validates use cases
4. **Analyzes changes** for security, testing, design patterns, and code quality issues
5. **Differentiates contexts**: CLI code vs GitHub Actions code (different standards)
6. **Creates actionable feedback**: Specific refactoring suggestions based on file names and patterns
7. **Verifies documentation completeness** — detects user-visible surface changes (new CLI flags, renamed public types, payload contract changes, etc.) and verifies `CHANGELOG.md` + relevant `README.md`/`design.md` are updated in the same diff. For renames, greps all `*.md` files for stale references. See the Documentation Completeness section in `.claude/agents/pr-code-reviewer.md` for detection rules and severity calibration.
8. **Runs the test suite and measures per-test timing** — flags any test taking > 1 second as a performance regression
9. **Generates structured review document** saved to a markdown file
10. **Shows summary** of all issues found organized by severity

## Engineering Review Principles

This skill enforces the same principles as the PR review skill:

### Architectural Review
- **Design Decision Validation**: Questions "why" before reviewing "how"
- **Scope Creep Detection**: Flags expansions beyond Agent365 deployment/management
- **Use Case Validation**: Requires concrete scenarios for new features
- **Overlap Detection**: Identifies duplication with existing tools (Azure CLI, Portal)
- **YAGNI Enforcement**: Questions features without documented need

### Architecture & Patterns
- **.NET architect patterns**: Reviews follow .NET best practices
- **Azure CLI alignment**: Ensures consistency with az cli patterns and conventions
- **Cross-platform compatibility**: Validates Windows, Linux, and macOS compatibility (for CLI code)

### Design Patterns
- **KISS (Keep It Simple, Stupid)**: Prefers simple, straightforward solutions
- **DRY (Don't Repeat Yourself)**: Identifies code duplication
- **SOLID principles**: Especially Single Responsibility Principle
- **YAGNI (You Aren't Gonna Need It)**: Avoids over-engineering
- **One class per file**: Enforces clean code organization

### Code Quality
- **No large files**: Flags files over 500 additions
- **Function reuse**: Encourages reusing functions across commands
- **No special characters**: Avoids emojis in logs/output (Windows compatibility)
- **Self-documenting code**: Prefers clear code over excessive comments
- **Minimal changes**: Makes only necessary changes to solve the problem

### Testing Standards
- **Framework**: xUnit, FluentAssertions, NSubstitute for .NET; pytest/unittest for Python
- **Quality over quantity**: Focus on critical paths and edge cases
- **CLI reliability**: CLI code without tests is BLOCKING
- **GitHub Actions tests**: Strongly recommended (HIGH severity) but not blocking
- **Mock external dependencies**: Proper mocking patterns
- **Test performance — measured by running, not just static analysis**: The review ALWAYS runs the full test suite and reports per-test timing. Any test method taking **> 1 second** is flagged as a performance regression (HIGH severity). The finding must include:
  - The slow test class and method name(s) with their measured time
  - The root cause (cold `AzCliHelper` token cache, missing `WarmAzCliTokenCache` call, real subprocess not mocked, etc.)
  - The fix (warmup call pattern, `loginHintResolver` injection, etc.)
  - Expected time after fix

  If all tests complete in < 1 second each: emit an **INFO — PASS** finding with the total suite time.

  **Do not skip the test run.** Static code analysis alone missed the regression in `da6f750`; only measurement catches it reliably.

### Security
- **No hardcoded secrets**: Use environment variables or Azure Key Vault
- **Credential management**: Follow az cli patterns for CLI code; use GitHub Secrets for Actions

### Documentation Completeness
The review does not assume docs will be updated later — a user-visible surface change without matching doc updates is a finding in its own right. Full detection rules live in `.claude/agents/pr-code-reviewer.md` (Step 7). Short version:
- **Detect**: new `Option<...>`, renamed public class/interface, new/deleted `public` API, changed payload shape or validation rules, changed observable log messages.
- **Require**: matching entry in `CHANGELOG.md` under `[Unreleased]`, updated `README.md` in the relevant folder, and — for renames — zero stale hits from `grep -rn "<OldName>" --include="*.md"`.
- **Severity**: missing CHANGELOG for user-visible change = **HIGH**; stale rename in markdown = **HIGH**; missing folder README update = **MEDIUM**.
- **Not excuses**: "it's preview/opt-in/temporary", "Microsoft Learn will cover it", "you can see it in the diff". The CHANGELOG is the release's source of truth.

### Context Awareness
The skill differentiates between:
- **CLI code** (strict requirements): Cross-platform, reliable, must have tests
- **GitHub Actions code** (GitHub-specific): Linux-only is acceptable, tests strongly recommended

## Review Output

Generated review is saved to:
```
.codereviews/claude-staged-<timestamp>.md
```

The review includes:
- **Summary**: Overview of changes and key concerns
- **Critical Issues**: Blocking issues that must be fixed
- **High Priority**: Important issues that should be addressed
- **Medium Priority**: Issues that improve code quality
- **Low Priority**: Suggestions for enhancement
- **Informational**: Best practices and recommendations

## Implementation

The skill uses **Claude Code directly** for semantic code analysis (same as review-pr):

1. Claude Code reads `.claude/agents/pr-code-reviewer.md` for review process guidelines
2. Claude Code reads `.github/copilot-instructions.md` for coding standards
3. Claude Code gets staged files: `git diff --staged --name-only`
4. Claude Code gets staged changes: `git diff --staged`
5. **Claude Code reads the complete current content of every staged file** (not just diff lines) to enable full-file semantic analysis.
5a. **If any staged file is a test file** (path contains `.Tests.` or filename ends in `Tests.cs`), Claude Code MUST also invoke the `pr-test-analyzer` agent as a subagent to review test coverage quality. Pass the staged diff and list of staged test files as context. The `pr-test-analyzer` agent focuses on:
   - NSubstitute predicate precision (predicates on mutable reference types evaluated at assertion time vs. call time)
   - Missing test scenarios for new orchestration code paths (e.g., 409 idempotent path, tri-state verification results)
   - Assertions that track implementation rather than requirements
   - Test method names that accurately describe the contract being verified
   Include the `pr-test-analyzer` findings in the review document under a dedicated **Test Coverage** section. This is critical for catching issues that exist in unchanged sections of modified files, such as:
   - Duplicate hardcoded constants or magic values that already exist elsewhere
   - Parallel code structures that should be consolidated (e.g., a method building the same spec list as a shared helper)
   - Unused or dead code that was already there but not touched by the diff
   - Missing calls to shared helpers — where the diff adds a new use but existing code still has the old duplicate pattern
   For each file path returned in step 3, Claude Code must `Read` the full file before performing analysis.
6. Claude Code performs semantic analysis using its own capabilities
7. Claude Code identifies specific issues with line numbers and code references
8. **Claude Code runs the full test suite with per-test timing:**
   ```bash
   cd src && dotnet test tests.proj --configuration Release --logger "console;verbosity=normal" 2>&1
   ```
   Parse the output for lines matching `[X s]` or `[X,XXX ms]` patterns. Extract test class name, method name, and duration. Flag any test method taking **> 1 second**. Group findings by test class and include the measured times in the review.
8. Claude Code writes markdown file to `.codereviews/claude-staged-<timestamp>.md`

**Test timing output format** (from `dotnet test --logger "console;verbosity=normal"`):
```
  Passed SomeTests.Method_Scenario_ExpectedResult [< 1 ms]
  Passed OtherTests.Method_Slow [22 s]
```
Any line showing `[X s]` where X ≥ 1 is a slow test. Report all such tests in a dedicated finding.

**Key Advantages**:
- ✅ No API key required - uses Claude Code's existing authentication
- ✅ Better semantic analysis - Claude Code has full context
- ✅ Catch issues before committing
- ✅ Same rigorous review standards as PR reviews
- ✅ Works offline (no GitHub required)

## Workflow

1. **Stage your changes**: `git add <files>`

2. **Review staged files**: `/review-staged`
   - Analyzes all staged changes
   - Generates review document
   - Shows summary of issues

3. **Address issues**: Fix any blocking or high-priority issues

4. **Re-review if needed**: `/review-staged`

5. **Commit**: `git commit -m "your message"`

## When to Use

- **Before committing**: Catch issues early
- **Before creating a PR**: Ensure quality before sharing
- **After addressing PR comments**: Verify fixes are correct
- **During code cleanup**: Validate refactoring changes
- **When learning**: Get feedback on coding patterns

## Requirements

- Git repository with staged changes
- Repository must follow Agent365 DevTools coding standards
- `.claude/agents/pr-code-reviewer.md` must exist (for review guidelines)
- `.github/copilot-instructions.md` must exist (for coding standards)

## See Also

- [README.md](README.md) - Detailed documentation
- `/review-pr` - Review pull requests on GitHub