cat:stakeholder-review

What this skill does

# Skill: stakeholder-review

Multi-perspective stakeholder review gate for implementation quality assurance.

## Purpose

Run parallel stakeholder reviews of implementation changes to identify concerns from multiple
perspectives (architecture, security, quality, testing, performance) before user approval.

## When to Use

- After implementation phase completes in `/cat:work`
- Before the user approval gate
- When significant code changes need multi-perspective validation

## Stakeholders

| Stakeholder | Reference | Focus |
|-------------|-----------|-------|
| requirements | @stakeholders/requirements.md | Requirement satisfaction verification |
| architect | @stakeholders/architect.md | System design, module boundaries, APIs |
| security | @stakeholders/security.md | Vulnerabilities, input validation |
| quality | @stakeholders/quality.md | Code quality, complexity, duplication |
| tester | @stakeholders/tester.md | Test coverage, edge cases |
| performance | @stakeholders/performance.md | Efficiency, resource usage |
| ux | @stakeholders/ux.md | Usability, accessibility, interaction design |
| sales | @stakeholders/sales.md | Customer value, competitive positioning |
| marketing | @stakeholders/marketing.md | Positioning, messaging, go-to-market |
| legal | @stakeholders/legal.md | Licensing, compliance, IP, data privacy |

## Progress Output

This skill orchestrates multiple stakeholder reviewers as subagents. Each reviewer's
internal tool calls are invisible - users see only the Task tool invocations and
aggregated results.

**On start:**
```
◆ Running stakeholder review...
```

**During execution:** Task tool invocations appear for each reviewer spawn, but their
internal file reads and analysis are invisible.

**On completion:**
```
✓ Review complete: {APPROVED|CONCERNS|REJECTED}
  → requirements: ✓
  → architect: ✓
  → security: ⚠ 1 HIGH
  → tester: ✓
  → performance: ✓
```

The aggregated result provides all necessary information without exposing 50+ internal
tool calls from reviewers.

## Process

<step name="analyze_context">

**Context-Aware Stakeholder Selection**

Analyze task context to determine which stakeholders are relevant, reducing token usage by skipping irrelevant reviewers.

### Selection Algorithm

```
RESEARCH MODE (pre-implementation):
1. Start with base set: [requirements] (always included)
2. Detect task type from PLAN.md or commit messages
3. Apply task type inclusions/exclusions
4. Scan task description/goal for keywords
5. Apply keyword inclusions
6. Check version PLAN.md for focus keywords
7. Apply version focus inclusions
8. Output: selected_stakeholders, skipped_with_reasons

REVIEW MODE (post-implementation):
1. Start with research mode selection
2. Get list of actually changed files
3. For each file-based override rule:
   - If condition matches, ADD stakeholder (even if context excluded it)
4. Output: final_stakeholders, skipped_with_reasons, overridden_stakeholders
```

### Task Type Mappings

Detect task type from PLAN.md `## Type` field or infer from commit messages/description:

| Task Type | Include | Exclude |
|-----------|---------|---------|
| documentation | requirements | architect, security, quality, tester, performance, ux, sales, marketing |
| refactor | architect, quality, tester | ux, sales, marketing |
| bugfix | requirements, quality, tester, security | sales, marketing |
| performance | performance, architect, tester | ux, sales, marketing |

### Keyword Mappings

Scan task description, goal, and PLAN.md for keywords:

| Keywords | Include |
|----------|---------|
| "license", "compliance", "legal" | legal |
| "UI", "frontend", "user interface" | ux |
| "API", "endpoint", "public" | architect, security, marketing |
| "internal", "tooling", "CLI" | architect, quality (exclude ux, sales, marketing) |
| "security", "auth", "permission" | security |

### Version Focus Mapping

Check version PLAN.md for strategic focus:

- If version PLAN.md mentions "commercialization" → include legal, sales, marketing

### File-Based Overrides (Review Mode Only)

In review mode, file changes can override context exclusions:

| File Pattern | Add Stakeholder |
|--------------|-----------------|
| UI/frontend files (`**/ui/**`, `**/frontend/**`, `*.tsx`, `*.vue`) | ux |
| Security-sensitive files (`**/auth/**`, `**/permission/**`, `**/security/**`) | security |
| Test files (`*Test*`, `*Spec*`, `*_test*`) | tester |
| Algorithm-heavy files (sort, search, optimize, process) | performance |
| Only .md files changed | requirements only, exclude all others |
| Only test files changed | tester, quality only |

### User Override: Force Stakeholders

Users can force specific stakeholders by adding to task PLAN.md:

```markdown
## Force Stakeholders
- ux
- legal
```

If `## Force Stakeholders` section exists, those stakeholders are ALWAYS included regardless of context analysis.

### Implementation

```bash
# Initialize base selection
SELECTED="requirements"
SKIPPED=""
OVERRIDDEN=""

# Read task PLAN.md
TASK_PLAN=$(cat .claude/cat/tasks/*/PLAN.md 2>/dev/null || echo "")

# Check for forced stakeholders
FORCED=$(echo "$TASK_PLAN" | sed -n '/## Force Stakeholders/,/^##/p' | grep '^ *-' | sed 's/^ *- *//')

# Detect task type
TASK_TYPE=$(echo "$TASK_PLAN" | grep -E '^## Type' -A1 | tail -1 | tr '[:upper:]' '[:lower:]' || echo "")
if [[ -z "$TASK_TYPE" ]]; then
    # Infer from commit messages or task name
    TASK_TYPE=$(git log -1 --pretty=%s 2>/dev/null | grep -oE '^(fix|feat|refactor|docs|perf)' | head -1)
    case "$TASK_TYPE" in
        docs) TASK_TYPE="documentation" ;;
        fix) TASK_TYPE="bugfix" ;;
        perf) TASK_TYPE="performance" ;;
    esac
fi

# Apply task type mappings
case "$TASK_TYPE" in
    documentation)
        EXCLUDED="architect security quality tester performance ux sales marketing"
        ;;
    refactor)
        SELECTED="$SELECTED architect quality tester"
        EXCLUDED="ux sales marketing"
        ;;
    bugfix)
        SELECTED="$SELECTED quality tester security"
        EXCLUDED="sales marketing"
        ;;
    performance)
        SELECTED="$SELECTED performance architect tester"
        EXCLUDED="ux sales marketing"
        ;;
    *)
        # Default: include core technical reviewers
        SELECTED="$SELECTED architect security quality tester performance"
        EXCLUDED=""
        ;;
esac

# Scan for keywords in task description
TASK_TEXT=$(echo "$TASK_PLAN" | tr '[:upper:]' '[:lower:]')

if echo "$TASK_TEXT" | grep -qE 'license|compliance|legal'; then
    SELECTED="$SELECTED legal"
fi
if echo "$TASK_TEXT" | grep -qE '\bui\b|frontend|user interface'; then
    SELECTED="$SELECTED ux"
fi
if echo "$TASK_TEXT" | grep -qE '\bapi\b|endpoint|public'; then
    SELECTED="$SELECTED architect security marketing"
fi
if echo "$TASK_TEXT" | grep -qE 'internal|tooling|\bcli\b'; then
    SELECTED="$SELECTED architect quality"
    EXCLUDED="$EXCLUDED ux sales marketing"
fi
if echo "$TASK_TEXT" | grep -qE 'security|auth|permission'; then
    SELECTED="$SELECTED security"
fi

# Check version PLAN.md for focus
VERSION_PLAN=$(cat .claude/cat/versions/*/PLAN.md 2>/dev/null || echo "")
if echo "$VERSION_PLAN" | grep -qi 'commercialization'; then
    SELECTED="$SELECTED legal sales marketing"
fi

# Add forced stakeholders
for stakeholder in $FORCED; do
    SELECTED="$SELECTED $stakeholder"
done

# Deduplicate and finalize selection
SELECTED=$(echo "$SELECTED" | tr ' ' '\n' | sort -u | tr '\n' ' ')
```

### File-Based Override Logic (Review Mode)

```bash
# Get changed files
CHANGED_FILES=$(git diff --name-only HEAD~1..HEAD 2>/dev/null || git diff --name-only --cached)

# Check for file-based overrides
if echo "$CHANGED_FILES" | grep -qE '(ui/|frontend/|\.tsx$|\.vue$)'; then
    if ! echo "$SELECTED" | grep -q 'ux'; then
        SELECTED="$SELECTED ux"
        OVERRIDDEN="$OVERRIDDEN ux:UI_file_changed"
    fi
fi

if echo "$CHANGED_FILES" | grep -qE '(auth/|permission/|security/)'; then
    if ! echo "$SE