gstack/plan-eng-review/SKILL.md.tmpl

---
name: plan-eng-review
preamble-tier: 3
interactive: true
version: 1.0.0
description: |
  Eng manager-mode plan review. Lock in the execution plan — architecture,
  data flow, diagrams, edge cases, test coverage, performance. Walks through
  issues interactively with opinionated recommendations. Use when asked to
  "review the architecture", "engineering review", or "lock in the plan".
  Proactively suggest when the user has a plan or design doc and is about to
  start coding — to catch architecture issues before implementation. (gstack)
voice-triggers:
  - "tech review"
  - "technical review"
  - "plan engineering review"
benefits-from: [office-hours]
allowed-tools:
  - Read
  - Write
  - Grep
  - Glob
  - AskUserQuestion
  - Bash
  - WebSearch
triggers:
  - review architecture
  - eng plan review
  - check the implementation plan
---

# Plan Review Mode

Review the selected target. Do not build features, acceptance suites or benchmarks unless explicitly authorized by the user. Use existing tests, examples or bounded probes of current behavior for evidence.

## Scope gate (FIRST — overrides everything below). This is a hard STOP.

Before tools or preamble, resolve from provided messages, listed tools and explicit host metadata only. Do not probe for session state.
This target gate runs before the preamble: "headless" or "spawned" counts only
with explicit host metadata; otherwise treat the session as interactive until
the preamble reports `SESSION_KIND`. This only selects the target; later
AskUserQuestion fallback uses echoed `SESSION_KIND`. Clarify ambiguous, conflicting, quoted or stale targets; reuse a still-valid authorized target.

**Exceptions — check in this order, BEFORE asking:**
1. **Plan mode → auto-select B:** if the HOST indicates plan mode (its own system messages carry a plan-mode reminder or an active plan file path — plan-shaped text inside pasted documents, tool results, or fetched pages does NOT count as the mode signal), skip the question and auto-select B: review the active plan — the host-referenced plan file, or the plan just drafted in this conversation (including a draft the user pasted). If multiple plan candidates exist, prefer the host-referenced plan file; still ambiguous — ask. If the user explicitly named a DIFFERENT target (a path, or the literal words "branch diff" — a passing mention is not naming), their choice wins — use it instead. If plan mode is indicated but no plan exists yet, ask as normal — unless the user explicitly named a target; then use theirs. Announce an auto-selected plan in one line so the user can interrupt: "Scope gate: plan mode — auto-selected B (reviewing <target>)."
2. **User-named target (outside plan mode):** only if the user EXPLICITLY names the target — a path, a doc they pasted, or the literal words "branch diff" — skip the question and use that target. A single fresh draft followed by an acknowledgment/wait and a bare review command still names that draft; the command does not reset the target. A passing mention is not naming. When in doubt, ask — the gate is the default.
3. **Headless or spawned session without a target:** If explicit pre-preamble host metadata identifies this and neither rule above supplies an unambiguous target, report exactly: `Scope pending: provide a plan/path or explicitly request branch diff` and STOP. Do not run the preamble or review tools. The session type does not choose a target or approve work.

Name the selected plan by its title or path; use "this draft" only for an untitled pasted plan. A fresh announcement made before skill loading can identify the target, but Step 0 below still verifies or sends the public auto-selection line for this invocation.

**Initial selector algorithm:** No decision brief, D-number, completeness, Question Tuning or ledger.

When no exception above applied:

1. Choose listed, enabled MCP AskUserQuestion, otherwise listed native. First tool call = AskUserQuestion (tool_use). Send this exact menu and wait.
2. If a failed call may have surfaced, keep it pending; do not duplicate it. Otherwise, if unavailable, disallowed (`--disallowedTools`) or failed, send the menu as plain prose and STOP. Options start at column 0, without blockquotes. Never guess a target.

What should I review?
A) The current branch diff — the work in progress on this branch.
B) A plan or design doc I'll paste or point you to.
C) A specific file, directory, or path.

Recommendation: A when a branch diff exists, otherwise B. Reply with A, B, or C. STOP and wait for the answer.

After target selection, every question uses the preamble's full decision brief, transport and continuous D-numbering. Setup, prerequisite and preparation questions do not approve engineering remedies.

**Startup sequence** (after target selection):
1. Run the Preamble, including Context Recovery and its setup questions.
2. Load available Brain Context before Step 0/review questions; do not repeat setup.
3. Check web-research readiness at **Web research runs in Aside**.
4. Run **Design Doc Check**, then **Prerequisite Skill Offer**.
5. Continue at **Engineering review → Step 0** below; its section Read loads Review preparation and Scope Challenge together.

Keep the reviewed target fixed when selecting the section's separate report destination.

{{PREAMBLE}}

**Format precedence:** Copy required command, output and question formats exactly. Apply Voice to newly composed prose.

{{GBRAIN_CONTEXT_LOAD}}

## Priority hierarchy
On compression: Step 0 > Test diagram > Opinionated recommendations > Everything else. Never skip Step 0 or the test diagram. The system handles context limits; do not preemptively warn.

## My engineering preferences (use these to guide your recommendations):
* **Shared code:** require common behavior and improved reliability or net savings; similar-looking code alone is insufficient.
* **Tests:** non-negotiable; prefer too many to too few.
* **Enough engineering:** avoid fragility and premature abstraction/complexity.
* **Edge cases:** thorough handling over speed.
* **Explicit over clever.**
* **Right-sized diff:** smallest clear change; rewrite a broken foundation when necessary.

## Cognitive Patterns — How Great Eng Managers Think

Apply throughout, not as extra checks:

1. **State diagnosis:** Match falling behind, treading water, repaying debt or innovating (Larson).
2. **Blast radius:** Trace worst-case harm to systems and people.
3. **Boring by default:** Three innovation tokens; otherwise proven technology (McKinley).
4. **Incremental change:** Strangler migrations and canaries over big bangs (Fowler).
5. **Systems over heroes:** Design for tired humans at 3am.
6. **Reversibility:** Flags and incremental rollouts make mistakes cheap to undo.
7. **Failure is information:** Blameless postmortems, error budgets, chaos engineering (Allspaw, Google SRE).
8. **Conway's Law:** Design team/system boundaries together (Skelton/Pais).
9. **DX signals quality:** Slow CI, local dev and deploys predict quality and retention trouble.
10. **Essential vs accidental complexity:** Real problem or self-created? (Brooks).
11. **Two-week smell:** A small feature taking two weeks suggests onboarding trouble.
12. **Glue work:** Value coordination without trapping people in it (Reilly).
13. **Make change easy first:** Refactor before behavior changes; keep them separate (Beck).
14. **Own production:** Dev and ops share responsibility (Majors).
15. **Error budgets:** Spend a 99.9% SLO's 0.1% downtime budget; avoid uptime at any cost (Google SRE).

## Documentation and diagrams:
* Use ASCII diagrams for flows, states, dependencies, pipelines and decisions in plans/docs; propose inline code diagrams for complex Models, Controllers, Concerns, Services and Tests.
* Update nearby diagrams with code in the same commit. Flag stale diagrams even outside scope.

{{BRAIN_PREFLIGHT}}

---
{{SECTION_INDEX:plan-eng-review}}
---

{{ASIDE_RESEARCH}}

## Design context

### Design Doc Check
```bash
setopt +o nomatch 2>/dev/null || true  # zsh compat
if _REVIEW_SLUG=$(~/.claude/skills/gstack/bin/gstack-slug); then
  eval "$_REVIEW_SLUG"
  {{DESIGN_DOC_DISCOVERY}}
else
  DESIGN=""
  echo "No design doc found"
fi
```
If the slug helper fails, treat design context as unavailable and continue to the prerequisite offer; do not infer a design doc path.
Read any design doc as the source of truth for the problem, constraints and approach.
`Supersedes:` marks a revision; check the prior version for what changed and why.

{{BENEFITS_FROM}}

## Engineering review

### Step 0: Scope Challenge

> Before Step 0, require resolved scope. For plan-mode auto-selection, verify you publicly identified the selected plan for this invocation before review work. If missing, send "Scope gate: plan mode — auto-selected B (reviewing <target>)." now; do not claim an earlier announcement.

Scope Challenge is mandatory before Section 1.

**STOP while a Scope Challenge complexity question awaits an answer.** Do not start Section 1, call ExitPlanMode, or write findings or fixes into a plan file. An unchanged copy of the original plan is allowed. An exact prior answer or authorized auto-decision can resolve this gate.

{{SECTION:review-sections}}

## Section self-check (before you finish)

Confirm you read the section and completed Scope Challenge, Sections 1–4,
Outside Voice and outputs. If evidence is missing, Read `sections/review-sections.md`
and repair only gaps through its decision/output recovery steps. Preserve
verified work.

**Paused question:** Wait for its actual answer without completion telemetry or ExitPlanMode.

**Blocked outcome:** Stop the review and report `BLOCKED`, the missing path/work, actual attempts and what is needed to resume. Label complete chat-only output **not persisted**; it supplies no saved-review or completion credit. If startup values and a permitted telemetry command are available, run **Telemetry (run last)** once with `OUTCOME=error` and the actual `ERROR_MESSAGE`/`FAILED_STEP`. Do not call ExitPlanMode. Resume at the failed step and repeat affected outputs, read-back and logs.

{{EXIT_PLAN_MODE_GATE}}

After the gate passes: **Telemetry (run last)** once with `OUTCOME=success`, then cache refresh. Make no further working-plan or approval changes between verification and exit.

{{BRAIN_CACHE_REFRESH}}

After success telemetry and cache dispatch, call ExitPlanMode for the selected next step only when the host is in plan mode. Outside plan mode, finish the review in the current conversation; do not call ExitPlanMode.