---
name: bigstack-plan-eng-review
version: 0.1.0
description: |
  Architecture and engineering plan review. Four-section review
  with cognitive bias patterns, scope challenge, and worktree
  parallelization strategy assessment.
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep
  - AskUserQuestion
---
<!-- Auto-generated from SKILL.md.tmpl by bigstack. DO NOT EDIT. -->
<!-- Regenerate: npm run gen:skill-docs -->

<!-- bigstack v0.1.0 | skill: bigstack-plan-eng-review -->

> **bigstack v0.1.0** — skills for Bigscreen development.

Before starting, run this setup block silently:

```bash
# Session context
BIGSTACK_VERSION="0.1.0"
BIGSTACK_DIR="C:/Users/GGPC/Documents/Github/bigstack"
REPO_NAME=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "bigstack v$BIGSTACK_VERSION | repo: $REPO_NAME | branch: $BRANCH"
```

**Guidelines:**
- When asking the user a question, use AskUserQuestion (not inline text questions)
- When uncertain about a change, state your confidence level before proceeding
- Prefer modifying existing code over creating new files
- This is an existing codebase — understand before changing

# /bigstack-plan-eng-review — Architecture Review

Review an engineering plan or architecture proposal for an existing codebase.

## Base Branch Detection

```bash
# Detect the base branch for PR targeting
BASE_BRANCH=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo "")
if [ -z "$BASE_BRANCH" ]; then
  if git show-ref --verify --quiet refs/heads/main 2>/dev/null; then
    BASE_BRANCH="main"
  elif git show-ref --verify --quiet refs/heads/master 2>/dev/null; then
    BASE_BRANCH="master"
  else
    BASE_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}' || echo "main")
  fi
fi
echo "Base branch: $BASE_BRANCH"
```

## Input

The user should provide one of:
- A plan document (file path or pasted text)
- A PR description or issue with a proposed approach
- A verbal description of what they want to build

## Review Structure

### Section 1: Understanding

Restate the plan in your own words:
- **Problem**: What is being solved?
- **Approach**: How does the plan solve it?
- **Scope**: What's included and excluded?
- **Existing constraints**: What existing code, APIs, or systems does this build on?

Ask the user to confirm your understanding before proceeding.

### Section 2: Architecture Assessment

Evaluate against these cognitive patterns:

| Pattern | Question |
|---------|----------|
| **Second-system effect** | Is this over-engineered relative to the problem? |
| **Premature abstraction** | Are abstractions justified by actual (not hypothetical) requirements? |
| **Distributed monolith** | Does this add network boundaries that create more problems than they solve? |
| **Leaky abstraction** | Will consumers need to understand the underlying implementation anyway? |
| **Stringly typed** | Are there type-safe alternatives to string-based APIs? |
| **God object** | Does any single component have too many responsibilities? |
| **Feature envy** | Does code in one module primarily access data from another? |
| **Shotgun surgery** | Will a single change require modifications across many files? |
| **Primitive obsession** | Should domain types replace primitive types? |
| **Temporal coupling** | Are there hidden ordering dependencies? |
| **Missing boundary** | Should there be an interface where direct coupling exists? |
| **Unnecessary indirection** | Are there layers that just pass through? |
| **Incomplete abstraction** | Does the abstraction only cover the happy path? |
| **Reinventing the wheel** | Does the existing stack already provide this? |
| **Existing code unawareness** | Is the plan duplicating functionality that already exists? |

**Critical for existing codebases**: Patterns 14 and 15 are especially important. Always search the existing codebase for similar functionality before approving new abstractions.

### Section 3: Scope Challenge

Challenge the scope:
- What's the **minimal version** that delivers value?
- What can be **deferred** to a follow-up?
- What **existing code** can be reused instead of written?
- What **dependencies** does this add, and are they justified?

### Section 4: Execution Strategy

Recommend:
- **Order of implementation** (what to build first)
- **Testing strategy** (what to test and how)
- **Migration plan** (if changing existing behavior)
- **Rollback plan** (how to undo if things go wrong)
- **Parallelization** (can parts be developed in worktrees concurrently?)

## Summary

| Dimension | Rating (1-5) | Notes |
|-----------|-------------|-------|
| Correctness | | Will it work? |
| Complexity | | Is it as simple as possible? |
| Compatibility | | Does it fit the existing codebase? |
| Completeness | | Does it cover edge cases? |
| Changeability | | Can it evolve without rewrites? |

**Verdict**: APPROVE / REVISE / RETHINK

## Confidence Calibration

Before completing a major action, state your confidence:

| Level | Meaning | Action |
|-------|---------|--------|
| **High** | Well-understood change, clear test coverage, matches existing patterns | Proceed |
| **Medium** | Reasonable approach but some uncertainty — unfamiliar area, partial test coverage | Proceed but flag risks |
| **Low** | Significant unknowns, could break existing behavior, no test coverage | Stop and ask the user |

Format: **Confidence: [High/Medium/Low]** — [one-line rationale]