Skip to content

m3dcodie/eng-flow / .claude/skills/eng-flow-eng-review

eng-flow-eng-review

Verified

Production Stage 3.5 — reviews a saved architecture.md against engineering-leadership judgment before it becomes epics/stories/tasks. Catches architecture problems while they're still cheap to fix (before backlog breakdown, before implementation), not a code review — no code exists yet at this point in the track.

FileKindSize
SKILL.mdskill md12.8 KB
---
name: eng-flow-eng-review
description: Production Stage 3.5 — reviews a saved architecture.md against engineering-leadership judgment before it becomes epics/stories/tasks. Catches architecture problems while they're still cheap to fix (before backlog breakdown, before implementation), not a code review — no code exists yet at this point in the track.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Write
  - Bash
  - AskUserQuestion
  - Agent
triggers:
  - engineering review
  - review the architecture
  - review this design
  - eng review
  - architecture review
---

# eng-flow engineering review

Stage 3.5 of the production track, between Architecture and Epics/Stories/Tasks. Reviews `architecture.md` for the kind of problems that are cheap to fix now and expensive to fix after a backlog is built on top of them — this is a design review, not a code review; no code exists yet at this point in the track.

## Analytics

At the start of every numbered step below (including Step 0), run `python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-analytics-checkpoint" eng-flow-eng-review "<step name>" "<dated-slug>"`. As the last action of Step 6, run `python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-analytics-finish" eng-flow-eng-review "<dated-slug>"`. See `eng-flow-spec`'s Analytics section for what this logs and why; rollup via `eng-flow-analytics` (Stage 10).

## Decision Ledger

Check `$ARGUMENTS` for a `--guide` token; if present, every decision point below gets an explicit `AskUserQuestion` instead of a silent default, and Step 6's report adds a "Decisions I made / decisions you made" summary. Log every decision point via `python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-decision-log" eng-flow-eng-review "<step>" <reason> <mode> <owner> "<description>" "<dated-slug>"`. See `eng-flow-spec`'s Decision Ledger section for the taxonomy and why. Rollup/analysis: `eng-flow-retro` Step 1 (Stage 9).

## Drafts

This stage saves as it goes to `eng-flow/.drafts/eng-review--<dated-slug>.json` (`<dated-slug>` is the spec folder's), so a crash loses at most the step in progress — in Step 4, only the issue in progress. The shared rules (Resume, Review, Discard, `in_progress` loops, input drift) are in `${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/draft-resume.md` — Read it before resuming, reviewing or discarding. Every save in this file is this call, with the step's JSON on stdin — short form, JSON-escaped:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-draft" save eng-flow-eng-review "<dated-slug>" <step> <<'EOF'
{"status": "done", "name": "<step name>", "answers": {…}}
EOF
```

Degrades silently like the analytics scripts — a failed save prints a warning and the run carries on.

## Step 0 — Find the inputs

Look for `eng-flow/specs/*/architecture.md` and the `domain-model.md` / `spec.md` in the same folder. If `architecture.md` is missing, tell the user to run Stage 3 first — there's nothing to review yet. Check for drafts: `python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-draft" list eng-flow-eng-review` — one line per draft, starting with the spec folder's `<dated-slug>`. If more than one spec folder exists, ask which one this run is for; a folder with a draft gets "draft: stopped after Step n, age" in its option description. If the chosen folder (or the only one) has a draft → **Resume** (`draft-resume.md`) — no further Step 0 questions.

Read all three: the spec's constraints and NFRs, the domain model's entities/relationships, and the architecture's tech stack, diagram, API contracts, NFR targets, and deployment topology.

Also look for `eng-flow/security-policy.md` (project-level, optional — established at Stage 3 if the project has one). Read it if present; if absent, note it in the report and fall back to the generic security-architecture check below.

As the last action of this step (new run only), save step 0 (`"name": "Find the inputs"`) with `topic` (the spec's title), `spec_folder` and `security_policy` (`present` or `absent`), then record the inputs — add `eng-flow/security-policy.md` to the list if present:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-draft" inputs eng-flow-eng-review "<dated-slug>" "eng-flow/specs/<dated-slug>/spec.md" "eng-flow/specs/<dated-slug>/domain-model.md" "eng-flow/specs/<dated-slug>/architecture.md"
```

**Resume notes:** if the input check reports `architecture.md` changed and the draft stopped before Step 5, someone edited it after the review started — the findings may be stale; if the user wants a fresh review, `truncate ... 0` and continue at Step 1. If the draft stopped *in* Step 5, the change is most likely this run's own partial edits — see Step 5.

---

## Step 1 — Architecture review checklist

Walk `architecture.md` against:
- **Component boundaries and coupling** — do the container-level boxes reflect real seams, or is this one thing pretending to be several (or several things pretending to be one)?
- **Data flow bottlenecks** — any path where everything funnels through one component under the stated load/scale targets?
- **Scaling characteristics and single points of failure** — does the deployment topology have one of anything that can't be one of anything?
- **Security architecture** — auth model, data-at-rest/in-transit handling, API boundary trust assumptions — actually specified, not just "secure" as an adjective. If `eng-flow/security-policy.md` exists, check `architecture.md` explicitly addresses each of its stated rules — a gap here is a finding like any other, not a pass by default.
- **Failure scenario per integration point** — for each external dependency or service boundary in the diagram, is there a stated realistic failure mode and whether the design accounts for it?
- **Distribution path** — if this introduces a new deployable artifact, is the build/publish/deploy path part of the doc (or explicitly deferred), not silently assumed?

As the last action of this step, save step 1 (`"name": "Checklist"`) with `findings` — one entry per finding with `title`, `section`, `issue` and `fix` (an empty list if none).

---

## Step 2 — Cognitive-pattern lenses

Apply these where relevant — not every pattern applies to every architecture, don't force one in. Adapted from gstack's `plan-eng-review` (attribution: `docs/DECISIONS.md`), scoped down to the seven that apply before any code exists:

1. **Boring by default** — every project gets a few "innovation tokens." Is anything novel/unproven in Step 1 of the architecture spending one without a stated reason?
2. **Blast radius** — for each major decision, what's the worst case, and how much does it affect if wrong?
3. **Conway's Law** — does the container boundary match how the team is actually structured, or does it assume coordination that won't happen?
4. **Essential vs. accidental complexity** — for anything non-obvious in the design, is it solving a real constraint from the spec, or one the design created?
5. **Two-week smell test** — could a competent engineer joining the project ship a small, representative feature within this architecture in about two weeks? If not, that's an onboarding problem wearing an architecture costume.
6. **Incremental over revolutionary** — does the deployment/rollout path allow incremental delivery (staged rollout, feature flags), or does it require a big-bang cutover?
7. **Reversibility preference** — for the decisions marked expensive-to-reverse (the ones that got ADRs in Stage 3), is the cost of being wrong actually low, or does the doc lock in something hard to undo without saying so?

As the last action of this step, save step 2 (`"name": "Cognitive lenses"`) with `findings` — same shape as Step 1, plus `lens`.

---

## Step 3 — Independent subagent review

Steps 1-2 ran in this conversation — often the same one that just wrote `architecture.md` in Stage 3. That's a self-review risk: the reasoning that produced a decision is the reasoning most likely to rubber-stamp it. Counter it with one blind pass.

Spawn a single `Agent` call (foreground — its output feeds Step 4, so wait for it) with `subagent_type: "eng-flow:eng-flow-doc-reviewer"` — a read-only plugin agent (Read, Grep, Glob only) that carries the review criteria. Give it **only the run-specific inputs, not this conversation's context or Steps 1-2's findings**:

> "Review: architecture. Files: `eng-flow/specs/<dated-slug>/spec.md`, `eng-flow/specs/<dated-slug>/domain-model.md`, `eng-flow/specs/<dated-slug>/architecture.md`."

**Fallback:** if `eng-flow:eng-flow-doc-reviewer` isn't in the Agent tool's list (the plugin agents didn't load — e.g. the skills are running from a checkout, not an installed plugin), read `${CLAUDE_PLUGIN_ROOT}/agents/eng-flow-doc-reviewer.md` (`agents/eng-flow-doc-reviewer.md` in an eng-flow checkout), and send its body below the frontmatter, followed by the same inputs, as the prompt of a `general-purpose` `Agent` call. Log it: `risk silent_decide ai_default "agent eng-flow-doc-reviewer unavailable: general-purpose fallback"`. Never skip the review because the agent is missing.

Adapted from gstack's `autoplan` dual-voice eng review (attribution: `docs/DECISIONS.md`) — without its Codex cross-check or consensus-table mechanics, since eng-flow has no second external reviewer and Step 4 already gets each finding an explicit human accept/change/reject.

Merge the subagent's findings with Steps 1-2's into one list for Step 4, tagging each by source (`checklist` / `cognitive lens` / `independent review`). Drop exact duplicates, but keep two findings that reach the same conclusion by different reasoning — that agreement is itself informative.

As the last action of this step, save step 3 (`"name": "Independent review"`) with `issues` — the merged list in the order Step 4 will raise them, each with `title`, `source`, `section`, `issue`, `severity` and `fix` — so a resume doesn't spawn the reviewer again.

---

## Step 4 — Interactive review, one issue at a time

For each issue surfaced in Steps 1-3, call `AskUserQuestion` individually — one issue per call, never batched. For each: name the issue, note its source tag, ground it in the specific section/decision of `architecture.md` it's reacting to (quote or point to the relevant line — a finding that can't be tied to actual doc text doesn't get raised), state options, give an opinionated recommendation, explain why.

**Stop and wait for the user's answer before raising the next issue.** Don't assume the "obvious fix" and move on — every issue gets an explicit accept/change/reject from the user, same discipline as every other stage in this track.

Log each: `risk open_question <user_confirmed|user_revised> "issue '<title>': accepted|changed|rejected"`.

If Steps 1-3 turn up nothing worth raising, say so plainly — a clean pass is a valid outcome, don't manufacture issues to fill the step.

After each issue, save step 4 as `{"status": "in_progress", "name": "Issues", "answers": {"resolved": [...]}}` — every issue answered so far, each with `title` and `resolution` (`accepted`, `changed` with what changed, or `rejected` with the reason). On resume, raise only the issues from step 3's list that aren't in `resolved`. After the last issue (or straight away if there were none), save it as `"done"` with the same field.

---

## Step 5 — Record the outcome

Write `eng-flow/specs/<dated-slug>/eng-review.md`:

```markdown
# Engineering Review: [Name]
(source: architecture.md in this folder)

## Findings

### [Issue title]
**Source:** [checklist | cognitive lens | independent review]
**Section:** [architecture.md section/decision this reacts to]
**Issue:** [what's wrong and why]
**Resolution:** [Accepted — architecture.md updated | Changed — describe | Rejected — reason]
```

For any finding marked "Accepted" or "Changed," update `architecture.md` directly to reflect the resolution — the review doc is the log, `architecture.md` stays the current source of truth.

Build both from step 3's `issues` and step 4's `resolved`. When resuming into this step, a crash may have left some `architecture.md` edits already applied — read it and skip any resolution it already reflects, so nothing is applied twice.

As the last action of this step, once `eng-review.md` is written and `architecture.md` updated, delete the draft: `python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-draft" clear eng-flow-eng-review "<dated-slug>"`. If either write failed, skip this and keep the draft; tell the user.

---

## Step 6 — Report back

Summarize what was reviewed, what changed (if anything), and confirm `architecture.md` is up to date. Tell the user this feeds Stage 4 (epics/stories/tasks).

If this run was in guide mode, add a "Decisions I made / decisions you made" summary here, drawn from this run's `eng-flow-decision-log` calls.

Run the Step 6 analytics-finish call (see Analytics section above) before ending.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall