Help us improve
Share bugs, ideas, or general feedback.
From vibeflow
Reviews execution plans for architecture, data flow, diagrams, edge cases, test coverage, and performance. Activated by phrases like 'review the architecture' or 'engineering review'.
npx claudepluginhub ttttstc/vibeflow --plugin vibeflowHow this skill is triggered — by the user, by Claude, or both
Slash command
/vibeflow:vibeflow-plan-eng-reviewThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Engineering Manager 视角的计划审查。锁定执行计划——架构、数据流、图表、边界情况、测试覆盖率、性能。在实施前捕获架构问题。
Interactively reviews implementation plans before coding, challenging scope creep, architecture, quality, tests, and performance with mandatory user checkpoints and opinionated recommendations.
Reviews architecture of written plans: scores data flow, failure modes, edge cases, test matrix, rollback safety (0-10 each) with citations; produces ranked fixes.
Runs expert review on plans, specs, or implementation approaches using parallel reviewer agents. Presents findings as Socratic questions. Useful before implementation to validate architectural decisions.
Share bugs, ideas, or general feedback.
Engineering Manager 视角的计划审查。锁定执行计划——架构、数据流、图表、边界情况、测试覆盖率、性能。在实施前捕获架构问题。
启动宣告: "正在使用 vibeflow-plan-eng-review 运行工程评审。"
ALWAYS follow this structure for every AskUserQuestion call:
RECOMMENDATION: Choose [X] because [one-line reason] — always prefer the complete option over shortcuts (see Completeness Principle). Include Completeness: X/10 for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work. If both options are 8+, pick the higher; if one is ≤5, flag it.A) ... B) ... C) ... — when an option involves effort, show both scales: (human: ~X / CC: ~Y)Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
Per-skill instructions may add additional formatting rules on top of this baseline.
AI-assisted coding makes the marginal cost of completeness near-zero. When you present options:
| Task type | Human team | CC+gstack | Compression |
|---|---|---|---|
| Boilerplate / scaffolding | 2 days | 15 min | ~100x |
| Test writing | 1 day | 15 min | ~50x |
| Feature implementation | 1 week | 30 min | ~30x |
| Bug fix + regression test | 4 hours | 15 min | ~20x |
| Architecture / design | 2 days | 4 hours | ~5x |
| Research / exploration | 1 day | 3 hours | ~3x |
Anti-patterns — DON'T do this:
Before building infrastructure, unfamiliar patterns, or anything the runtime might have a built-in — search first.
Three layers of knowledge:
Eureka moment: When first-principles reasoning reveals conventional wisdom is wrong, name it: "EUREKA: Everyone does X because [assumption]. But [evidence] shows this is wrong. Y is better because [reasoning]."
WebSearch fallback: If WebSearch is unavailable, skip this step and note: "Search unavailable — proceeding with in-distribution knowledge only."
When completing a skill workflow, report status using one of:
It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."
Bad work is worse than no work. You will not be penalized for escalating.
Escalation format:
STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]
Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give me an opinionated recommendation, and ask for my input before assuming a direction.
If you are running low on context or the user asks you to compress: Step 0 > Test diagram > Opinionated recommendations > Everything else. Never skip Step 0 or the test diagram.
These are not additional checklist items. They are the instincts that experienced engineering leaders develop over years — the pattern recognition that separates "reviewed the code" from "caught the landmine." Apply them throughout your review.
When evaluating architecture, think "boring by default." When reviewing tests, think "systems over heroes." When assessing complexity, ask Brooks's question. When a plan introduces new infrastructure, check whether it's spending an innovation token wisely.
Check for existing design documents:
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
DESIGN=""
if [ -f .vibeflow/state.json ]; then
DESIGN=$(python scripts/get-vibeflow-paths.py --json | python -c "import json,sys; print(json.load(sys.stdin)['artifacts']['design'])")
fi
[ -z "$DESIGN" ] && DESIGN=$(ls -t docs/plans/*-$BRANCH-design-*.md 2>/dev/null | head -1)
[ -z "$DESIGN" ] && DESIGN=$(ls -t docs/plans/*-design-*.md 2>/dev/null | head -1)
[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found"
If a design doc exists, read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a Supersedes: field, note that this is a revised design — check the prior version for context on what changed and why.
Also check for brainstorming output if it exists:
BRAINSTORMING=$(ls -t docs/plans/*-brainstorming.md 2>/dev/null | head -1)
[ -n "$BRAINSTORMING" ] && echo "Brainstorming found: $BRAINSTORMING" || echo "No brainstorming doc found"
When the design doc check above prints "No design doc found," you may suggest running vibeflow-office-hours first to sharpen the problem statement. Say to the user:
"No design doc found. Running
vibeflow-office-hoursfirst produces a structured problem statement, premise challenge, and explored alternatives — it gives this review much sharper input to work with."
Options:
If they skip: proceed normally.
Before reviewing anything, answer these questions:
What existing code already partially or fully solves each sub-problem? Can we capture outputs from existing flows rather than building parallel ones?
What is the minimum set of changes that achieves the stated goal? Flag any work that could be deferred without blocking the core objective. Be ruthless about scope creep.
Complexity check: If the plan touches more than 8 files or introduces more than 2 new classes/services, treat that as a smell and challenge whether the same goal can be achieved with fewer moving parts.
Search check: For each architectural pattern, infrastructure component, or concurrency approach the plan introduces:
If WebSearch is unavailable, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only."
If the plan rolls a custom solution where a built-in exists, flag it as a scope reduction opportunity. Annotate recommendations with [Layer 1], [Layer 2], [Layer 3], or [EUREKA] (see preamble's Search Before Building section). If you find a eureka moment — a reason the standard approach is wrong for this case — present it as an architectural insight.
TODOS cross-reference: Read TODOS.md if it exists. Are any deferred items blocking this plan? Can any deferred items be bundled into this PR without expanding scope? Does this plan create new work that should be captured as a TODO?
Completeness check: Is the plan doing the complete version or a shortcut? With AI-assisted coding, the cost of completeness (100% test coverage, full edge case handling, complete error paths) is 10-100x cheaper than with a human team. If the plan proposes a shortcut that saves human-hours but only saves minutes with CC+gstack, recommend the complete version. Boil the lake.
If the complexity check triggers (8+ files or 2+ new classes/services), proactively recommend scope reduction via AskUserQuestion — explain what's overbuilt, propose a minimal version that achieves the core goal, and ask whether to reduce or proceed as-is. If the complexity check does not trigger, present your Step 0 findings and proceed directly to Section 1.
Evaluate:
STOP. For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.
Evaluate:
STOP. For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.
Make a diagram of all new UX, new data flow, new codepaths, and new branching if statements or outcomes. For each, note what is new about the features discussed in this branch and plan. Then, for each new item in the diagram, make sure there is a corresponding test.
STOP. For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.
Evaluate:
STOP. For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.
Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:
Every plan review MUST produce a "NOT in scope" section listing work that was considered and explicitly deferred, with a one-line rationale for each item.
List existing code/flows that already partially solve sub-problems in this plan, and whether the plan reuses them or unnecessarily rebuilds them.
After all review sections are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step.
For each TODO, describe:
Then present options: A) Add to TODOS.md B) Skip — not valuable enough C) Build it now in this PR instead of deferring.
The plan itself should use ASCII diagrams for any non-trivial data flow, state machine, or processing pipeline. Additionally, identify which files in the implementation should get inline ASCII diagram comments — particularly Models with complex state transitions, Services with multi-step pipelines, and Concerns with non-obvious mixin behavior.
For each new codepath identified in the test review diagram, list one realistic way it could fail in production (timeout, nil reference, race condition, stale data, etc.) and whether:
If any failure mode has no test AND no error handling AND would be silent, flag it as a critical gap.
At the end of the review, fill in and display this summary so the user can see all findings at a glance:
Check the git log for this branch. If there are prior commits suggesting a previous review cycle (e.g., review-driven refactors, reverted changes), note what was changed and whether the current plan touches the same areas. Be more aggressive reviewing areas that were previously problematic.
After completing all review sections, check if additional reviews would be valuable.
Suggest vibeflow-plan-design-review if UI changes exist and no design review has been run — detect from the test diagram, architecture review, or any section that touched frontend components, CSS, views, or user-facing interaction flows.
Mention vibeflow-plan-value-review if this is a significant product change and no CEO review exists — this is a soft suggestion. Only mention it if the plan introduces new user-facing features, changes product direction, or expands scope substantially.
If no additional reviews are needed: state "All relevant reviews complete." and summarize the completion status.
Use AskUserQuestion with only the applicable options:
If the user does not respond to an AskUserQuestion or interrupts to move on, note which decisions were left unresolved. At the end of the review, list these as "Unresolved decisions that may bite you later" — never silently default to an option.
docs/changes/<change-id>/design-review.md完成所有评审后,将评审结论写入 docs/changes/<change-id>/design-review.md 的 ## Engineering Review 小节:
# Plan Engineering Review — 执行层面审查结论
**日期**:YYYY-MM-DD
**分支**:[branch-name]
**评审模式**:[FULL_REVIEW / SCOPE_REDUCED]
## Step 0: Scope Challenge
[范围挑战结论]
## Architecture Review
[发现的问题及处理结果]
## Code Quality Review
[发现的问题及处理结果]
## Test Review
[测试缺口及建议]
## Performance Review
[性能问题及建议]
## NOT in scope
[明确排除的工作]
## What already exists
[现有可复用代码]
## Failure modes
[关键故障模式分析]
## Completion Summary
- Step 0: Scope Challenge — [结果]
- Architecture Review: [N] issues
- Code Quality Review: [N] issues
- Test Review: [N] gaps
- Performance Review: [N] issues
- Critical gaps: [N]
- Lake Score: [X]/[Y]
## Unresolved decisions
[待处理决策]
此文件由 vibeflow-design 在 Step 5.1 中自动调用后读取。
调用者: vibeflow-design(design 阶段 Step 5.1,用户审批之后执行)
依赖: docs/changes/<change-id>/design.md(设计文档)、.vibeflow/workflow.yaml、docs/changes/<change-id>/brief.md
产出: docs/changes/<change-id>/design-review.md(Engineering Review 小节)
Gate: 评审中发现的严重问题(critical)需要处理后才能进入 scope decision
链接到: vibeflow-plan-design-review(design 阶段 Step 5.2) → scope decision