Eng

---
description: >
  Engineering — scope, architecture decisions, implementation review, TDD plan.
  Technical planning for how to build what /spec defined.
    /eng            — auto-detect (arch + impl, or impl only)
    /eng arch       — force architecture mode (greenfield, major subsystem)
    /eng impl       — force implementation review only (architecture settled)
    /eng hold       — scope lock-down (make it bulletproof)
---

# Eng

Scope the work, make architecture decisions if needed, then review the
implementation plan with TDD enforcement. One gate, streamed output, rigor preserved.

**This is read-only. No code changes.** Exception: writes `specs/{slug}.md`
when no spec file exists — see §Inferred Spec Write.

> Follows `rules/integrity.md` — evidence-based, state assumptions (I8),
> neutrality check (I9), forward-looking durability (I10), question inherited
> rules (I11). Shared formatting + Visual Emphasis in `skills/shared/formatting.md`
> (use **bold** for decisions, tables over prose for comparisons, `> ▸`
> blockquotes for gates, ASCII diagrams for architecture/flow).

---

## When to use

| Signal | Mode |
|--------|------|
| Greenfield or major subsystem | `/eng` or `/eng arch` |
| Multiple interdependent decisions (>3) | `/eng arch` |
| After `/research`, need to decide | `/eng arch` |
| Feature work, architecture settled | `/eng` or `/eng impl` |
| Reviewing an existing implementation plan | `/eng impl` |
| Make an existing plan bulletproof | `/eng hold` |

---

## Complexity routing

| Complexity | Signal | Behavior |
|---|---|---|
| **Small** | ≤3 files, single clear fix | Single response. 1 gate (TDD plan). |
| **Medium** | 3–8 files, known architecture | Stream. 1 gate (combined overview + TDD plan). |
| **Large** | Greenfield, 8+ files, architecture decisions needed | Stream with per-decision cards. 1 gate (overview + ADRs + TDD plan). |

---

## Before you start

- Read **Project Profile** in consumer `CLAUDE.md`; adapt review checks to stack/architecture/testing/deploy.
- Scan `.retro/` for recurring issues in the affected area — flag as known risks.
- Read upstream artifacts — `/spec` and `/design` handoffs are full documents in context (no separate summary block). Read them directly.
- Check `specs/` for an existing spec matching this scope. If found, read it and reference its ACs throughout. If not found, an inferred spec will be generated after the gate.
- See §Gather Context for the standard bash snippet (branch, base, diff, TODOs).
- Build the **Impact Map** (`skills/shared/impact-map.md`) — grounded files, existing utilities, missing capabilities, blast radius.

### Graph-aware scoping (if `graphify` MCP is available)

- Query callers/dependents/affected tests for each Touches path — feeds risk assessment and TDD plan.
- Verify dependency direction matches declared architecture; flag violations before they compound.
- Max 3 graph queries per invocation (token budget).

Fall back to Grep + file reads if MCP is absent.

### Context7 verification (libraries, frameworks, APIs)

When architecture touches a library or API:

- `resolve-library-id` for each key library — confirm latest stable version matches usage.
- `query-docs` for load-bearing capabilities ("does X support Y?").
- If a capability can't be verified, mark it **Unverified** in the scope and recommend `/research` before committing.

**Limits:** 2 `resolve-library-id` + 2 `query-docs` during context gathering;
3 + 3 per architecture decision. This is verification, not research.

---

## Spec Challenge Gate

Read the spec while scanning for flaws. If any of these are found, raise a
**Spec Challenge** before proceeding:

| Flaw type | Example |
|-----------|---------|
| Contradictory requirements | "Must be real-time" + "batch process nightly" |
| Missing edge case | No handling for zero-quantity orders |
| Technically impossible | "Sub-millisecond response with full table scan" |
| Ambiguous acceptance criteria | "Should be fast" without a measurable target |
| Scope gap | Spec says multi-tenant but no AC tests tenant isolation |
| Inaccessible interaction | Flow needs sight/motor precision without alternative — drag-only, hover-only, color-only, gesture-only |

**Format:**

```
⚠ SPEC CHALLENGE
  Issue:    {what's wrong — specific, with evidence}
  Impact:   {what happens if we build as-is}
  Options:
    A) Fix spec — {what changes}
    B) Proceed with known risk — {risk accepted}
    C) Descope — {what to cut}
  Recommendation: {A, B, or C + one sentence why}
```

Spec challenges are inline — they surface in the `⚠ HEADLINE RISKS` block
of the inverted-pyramid header and the user addresses them at the single
gate. **Only stop for technically impossible requirements** (contradictions
that can't be resolved by design choice). All other challenges (missing edge
cases, ambiguous ACs, scope gaps) are surfaced as risks or questions, not
blockers.

If no flaws found, proceed silently — don't report "spec looks fine."

---

## Output structure — Option A inverted pyramid

`/eng` follows the **Inverted-Pyramid Output** pattern defined in
`skills/shared/formatting.md`. Read that section once; the rules below specify
only `/eng`-specific bindings.

### Progress block — canonical shape

This is the canonical shape of the progress block (for reference). **Do
not emit it as a separate "top of skill" banner.** Phase 1 is silent
(internal reasoning, no visible output), so Phase 2's full re-emit at the
start of the phase IS the entry banner — emitting it at the top too
duplicates the block back-to-back.

```
/eng ═════════════════════════════════════════════════════════════════════════════════

  ▸ Phase 1  Impact Map
  ○ Phase 2  Plan
  ○ Phase 3  Summary

══════════════════════════════════════════════════════════════════════════════════════
```

**Override of `skills/shared/formatting.md` "every invocation" banner rule:**
the canonical rule says emit a top banner at the start of every skill
invocation. `/eng` deviates — Phase 1 produces no visible output, so the
first thing the user sees is Phase 2's full block. That emission serves as
the entry banner and shows Phase 1 as `✓` (already done), Phase 2 as
`▸` (current).

No inline title — the topic appears inside `★ THE OVERVIEW` below in plain
English.

### Mode-specific markers

| Mode | Phase 2 marker | Notes |
|------|----------------|-------|
| `auto` | `○` then `▸` | Standard flow. |
| `arch` | `○` (forced) | Phase 2 includes ADRs explicitly. |
| `impl` | `— skipped` | Architecture settled; jump from Impact Map to Review. Overview is suppressed; inverted-pyramid header is leaner (THE OVERVIEW: 1 line, no DECISIONS block). |
| `hold` | `○` (locked) | Same as auto, Overview notes `(scope locked)`, Review challenges complexity harder. |

For Small complexity: collapse all phases to a single `▸ Eng (streaming)` marker.

---

## Flow

### Phase 1 · Impact Map (internal reasoning, no visible output)

Build the Impact Map per `skills/shared/impact-map.md`. **Reason fully but
emit nothing yet** — the map renders below the gate as `Receipts — File
Tree`. Phase 1 has no visible output of any kind: no banner, no transition
line, no progress block. The first thing the user sees is Phase 2's
progress-block re-emit (below), which serves as the entry banner.

**Tracker integration** — run the Tracker Detection block from
`skills/shared/tracker.md` §Tracker Detection if `TRACKER_TYPE` is not yet
cached. Then run the §Issue Resolution Block to resolve `TASK_ISSUE` from the
`Task:` handoff line, the user's invocation message, or the current branch
name. If `TRACKER_TYPE=github-issues` and `TASK_ISSUE` is resolved, swap the
issue's status label to `status:planning` using the §Status Swap Block. This
signals the task has entered the engineering phase.

### Phase 2 · Plan — emit overview, review, TDD plan, then single gate

Phase 2 emits the **full progress block** at the start of the phase as the
entry banner (Phase 1 ✓, Phase 2 ▸). This is the FIRST visible output of
`/eng` — there is no separate top banner above it. Then it emits in order:
inverted-pyramid header, overview receipts, review receipts, TDD plan
receipts, then waits at the single gate. Header density must match body
density.

```
/eng ═════════════════════════════════════════════════════════════════════════════════

  ✓ Phase 1  Impact Map
  ▸ Phase 2  Plan
  ○ Phase 3  Summary

══════════════════════════════════════════════════════════════════════════════════════
```

#### 2a · Inverted-pyramid header (must-read summary)

```
▎ ★ THE OVERVIEW
▎
▎ {1–2 plain-English lines: what's being built + scope.
▎ No mechanism, no decision content — those live in DECISIONS or receipts.}

▎ ⚠ HEADLINE RISKS
▎
▎ • {plain-language risk drawn from Impact Map · Risks}
▎ • {plain-language risk}
▎ • {2–3 bullets max}

▎ ✎ {N} DECISIONS
▎
▎ D1  {decision topic, ≤40 chars}    →  {answer, ≤8 words}
▎ D2  {decision topic}                →  {answer}
▎ ...
```

The header ends here. The gate prompt does **not** sit at the bottom of
the header — it moves below the receipts (§2c).

If `/eng impl` mode: the `✎ DECISIONS` block is omitted (architecture
settled). Header has `★ THE OVERVIEW` (1 line: "Implementing approved
approach.") + `⚠ HEADLINE RISKS`, then review streams immediately — no
overview section.

If `/eng arch` mode: `D1...DN` includes ADR-level decisions. Each gets a
full ADR card in `Receipts — Approach & Decisions`.

If `/eng hold` mode: `★ THE OVERVIEW` notes "Scope locked. No expansion."
Decisions still stream if any remain; review challenges complexity harder.

#### 2b · Receipts — between header and gate

After the header, emit receipts. **Lean format is the default.**

**Default (lean receipts):**

```
══ File Tree ═══════════════════════════════════════════════════════════════════

[Render the Impact Map — boxed form, same content.
 The file tree ALWAYS emits — it shows blast radius.
 See skills/shared/impact-map.md.]

══ Architecture ════════════════════════════════════════════════════════════════

[3A ASCII architecture diagram — same as §3A diagram.
 Emits here instead of inside the review section.
 Omit if trivial (single-file change, no new components).]
```

Suppress by default: Approach & Decisions table, alternatives, scope check,
implementation order, ADR cards. The HANDOFF carries the approach verdict.
User can surface these at any time via `receipts eng`.

**Verbose mode** (only when `Verbose: true` in HANDOFF or user said
"go verbose" at the entry-point gate):

```
══════════════════════════════════════════════════════════════════════════════════════
  Receipts — File Tree
══════════════════════════════════════════════════════════════════════════════════════

[Render the Impact Map here — boxed form is the default;
 see skills/shared/impact-map.md.]

══════════════════════════════════════════════════════════════════════════════════════
  Receipts — Approach & Decisions
══════════════════════════════════════════════════════════════════════════════════════

[Approach alternatives table; scope check; implementation order;
 ADR cards (arch/Large only); cross-cut validation; risk register.]
```

#### 2c · Overview gate suppressed — flows into review + TDD plan

Gate A is removed. The overview section flows directly into the review
receipts and TDD plan. The single gate appears after the TDD plan (see §2g).

#### Internal reasoning before writing the header (do NOT output)

- Right problem? Most direct path to the outcome?
- What exists? Map sub-problems to existing code. Flag unnecessary rebuilds.
- What if we ship nothing? (Only mention if doing nothing is genuinely viable.)

#### Approach alternatives

| | Approach A: {name} | Approach B: {name} | Approach C: {name} |
|---|---|---|---|
| **Summary** | {1–2 sentences} | {1–2 sentences} | {1–2 sentences} |
| **Effort** | S / M / L | S / M / L | S / M / L |
| **Risk** | Low / Med / High | Low / Med / High | Low / Med / High |
| **Reuses** | {existing code} | {existing code} | {existing code} |

> One must be "minimal viable" (smallest diff). One must be "ideal architecture".

**Scope check** (one line, prose):

```
Scope: {minimum-viable summary} · Complexity: {within budget | over — challenge} · TODOS: {no conflicts | conflict with X}
```

If complexity is over budget (>8 files or >2 new classes) or TODOS conflicts
exist, surface as a `⚠` warning below this line — don't bury inside a table.

**Scope guard — recommend `/decompose` when work exceeds one cycle.** If the
estimated work is >8 files, spans >2 modules, OR rates effort `L`, stop and
surface this recommendation before continuing the Overview:

```
⚠ SCOPE GUARD — work exceeds one /eng → /tdd cycle
  Signal:    {>8 files | >2 modules | effort L | combination}
  Risk:      single TDD plan becomes a 30-step megaplan; tests + impl drift apart
  Recommend: /decompose first — break into 3–8 sequenced tasks, then /eng per task
  Override:  reply "proceed" to continue with a single oversized plan (rare; usually wrong)
```

Mirrors `/spec`'s decompose recommendation (`skills/spec/SKILL.md` Next-step
table, ">12 ACs across 4+ component types" trigger). In autonomous-chain mode,
hand off to `/decompose` automatically; otherwise wait for the user.

**Implementation order** (skip if single-tier):

| Order | Tier | What to build | Why this order |
|-------|------|---------------|----------------|
| 1 | {tier} | {what} | {why first} |
| 2 | {tier} | {what} | depends on 1 |

**`/eng hold` only:** scope is locked — challenge complexity harder, skip expansion suggestions.

**Approach verdict** — single inline line, no block:

```
▸ APPROACH **{letter}** — {one short reason, ≤12 words}
```

Don't restate scope or order — those are covered above. Drop the verdict
entirely if the chosen letter is obvious from per-decision RECOMMENDs
(arch/Large mode with one alternative driving all decisions).

#### Architecture decisions (if arch mode or Large)

Process decisions **one at a time** in agreed order. For each, use this
three-block form — bold header, italic context line, real options table, bold
recommendation:

**DECISION #N — {title}**
*Context:* {why — 1 sentence} · *Depends on:* {prior decisions, or `—`}

| Option | Summary | Trade-off |
|--------|---------|-----------|
| A | {1 sentence} | {cost of choosing A} |
| B | {1 sentence} | {cost of choosing B} |
| C | {if needed} | {cost of choosing C} |

**Trade-off cell rule:** describes the *cost* of picking that option — not
arguments against it, not why you wouldn't pick it. ✗ "Two-bookkeeping; no
consumer needs the old model" mixes cost with reason-against. ✓ "Two state
models in flight during transition" states only the cost.

▸ **RECOMMEND: {letter}** — {one sentence why}

**Internal validation (do NOT output checklist rows):**

- OWASP security standards
- 12-Factor cloud-native
- Well-Architected (reliability, performance, cost)
- Consistency with prior decisions this session

If a violation is found, surface it inline in the recommendation or as a
warning below the decision card. If all pass, say nothing.

**Context7 per decision:** resolve-library-id + query-docs for the specific
capability; cite the source version in Context field. If Context7 lacks the
library, note it and recommend `/research` for that decision.

**Batch rule:** independent, low-impact decisions can be grouped in one table
with individual recommendations. Reserve one-at-a-time for interdependent
decisions.

**ADR recording (Large complexity only) — key-value markdown table:**

**ADR-{NNN} — {title}**

| | |
|---|---|
| **Status** | Accepted |
| **Date** | {today} |
| **Context** | {why — 1–2 sentences} |
| **Decision** | {what was decided} |
| **Consequences** | {positive} / {trade-off} |
| **Breaks if** | {I10 — load-bearing assumption whose change in 2–3 years would invalidate} |

For Small/Medium, the decision card itself is the record.

#### Cross-cut validation (after all decisions, signal-only)

If decisions conflict or create gaps:

```
⚠ CROSS-CUT ISSUE: {one-line summary}
  Detail    {what's wrong}
  Affected  ADR-{NNN}, ADR-{NNN}
  Fix       {recommendation}
```

If all decisions are consistent and no gaps exist, **emit nothing** for
cross-cut. Silence = pass. Skip the ceremonial green-check line.

**Risk register** — always output if architecture decisions were made:

| # | Risk | Severity | Mitigation |
|---|------|----------|------------|
| 1 | {description} | High/Med/Low | {plan} |

**Risk dedup rule:** A risk in `⚠ HEADLINE RISKS` is the headline. The
register adds severity + mitigation — that's its job. If a register row's
only addition is severity (no mitigation, no new detail), drop it; the
headline already covered it.

**Severity coherence rule:** The Approach alternatives table's `Risk` cell
is **comparative** across A/B/C — a relative rating of which approach
carries more risk overall. The Risk register lists **specific concerns**
with severity + mitigation. Do not double-rate the same concern across both
with conflicting labels (e.g., approach A "Low" while register flags the
defining concern of A as "High"). If a specific concern is High-severity,
the alternatives table's overall rating for that approach must reflect it.

**Decision semantics** — decisions are reviewed as part of the single gate at
the end of Phase 2. The user replies "go" to accept all sections or overrides
any. *Small complexity:* the overview section is minimal.

#### 2d · Review — signal-leads, receipts below (no separate gate)

After the overview receipts, the review section emits inline. **The
REVIEW summary emits first**, then sub-sections render as receipts below
a `══ Receipts — Review ══` separator. No gate here — present issues inline
and recommend fixes. Critical findings surface in the final gate prompt.

**Default (lean review):** Run the full 3A-3D checklist internally.
Emit ONLY the REVIEW summary line (see §3-Lead below). Suppress the
`══ Receipts — Review ══` separator and all sub-section output (3A finding
cards, 3B error table, 3C gap table, 3D concern list). The 3A ASCII
architecture diagram emits earlier in §2b (lean receipts). Findings from
3B/3C feed the TDD plan — the analysis happens, the verbose output doesn't.
User can surface full review at any time via `receipts eng review`.

**Verbose mode:** emit full 3A-3D sub-sections with finding cards, tables,
and `══ Receipts — Review ══` separator.

#### 3-Lead · REVIEW summary (emit first)

```
REVIEW · Arch: {N} issues ({N} critical) · Errors: {N} GAPS · Tests: {N} gaps · Perf: {N} concerns
  CRITICAL:   {list or "none"}
  DECISIONS:  {unresolved choices or "none — all clear"}
```

Then the receipts separator:

```
══════════════════════════════════════════════════════════════════════════════════════
  Receipts — Review
══════════════════════════════════════════════════════════════════════════════════════
```

Sub-sections (3A–3D) follow below the separator in order.

**Phase 3 receipts cadence — mirror Phase 2.** Inside `══ Receipts — Review ══`,
demarcate sub-sections with a **bold label** (`**3A · Architecture & Security**`,
`**3B · Error Handling**`, `**3C · Test Coverage**`, `**3D · Performance &
Deployment**`) followed by a blank line. No `─ Label ─` rule lines, no nested
`══` headers — Phase 2 receipts use bold labels for the same purpose
(`**Approach alternatives**`, `**Scope check**`, `**DECISION #1 — title**`),
and Phase 3 must match.

Within each sub-section, **bold artifact labels** (`**State:**`, `**Migration:**`,
`**Diagram:**` when the diagram needs an explicit anchor) further structure
content. Never emit orphan prose between artifacts.

#### 3A · Architecture & security

**Internal checklist (evaluate all; output only findings):**

- System diagram — always output ASCII diagram of new components and their relationships to existing ones
- Data flows, state machines, coupling — integrity, missing states, circular deps
- Scaling (10×) — what breaks at 10× current load; rollback — can this be reverted safely?
- Security — auth/authz gaps, unvalidated inputs, injection vectors, hardcoded secrets, supply-chain risk on new deps
- **Accessibility** (UI features only, signal-only) — flag if any of: missing keyboard path for an action, focus management absent on route/modal change, color-only state signaling, missing screen-reader announcement for async state change. Don't enumerate WCAG; surface only the load-bearing gap.
- **Runtime wiring** — routes, middleware, DI, event subscriptions, env vars, config. **Always surface if wiring is needed** — compiles-but-fails-at-runtime is a common bug class.
- Failure scenarios — external services down, degraded mode behavior

**Findings format** (only when a finding warrants the full card — otherwise
fold into the labeled-line composition below):

```
⚠ {area} — {one-line summary}
  Problem   {what's wrong}
  Impact    {what breaks}
  Fix       {recommendation}
  Severity  CRITICAL GAP | WARNING | INFO
```

If all checks pass: `✓ Architecture & security: no issues.`

**§3A composition order:** under the bold sub-section label, emit in this
order. Drop any line that has no content; never emit a label with empty body.

1. **ASCII diagram** — small, flat, **single tree, max 3 indent levels**.
   Drop nodes that only forward (a Provider that only re-exports a
   Context, a layout that only mounts a child). Annotation tags
   (`NEW`, `renamed`, `unchanged`) right-padded for vertical scan. Avoid
   deeply nested boxes — left-to-right flow with `─►` arrows beats stacked
   nesting. Counter-example to avoid: `Provider → Context.Provider →
   flex-wrap → child-1 / child-2 → grandchild` (5 levels) — collapse the
   forwarding nodes and right-align annotations.
2. **State / A11y / Wiring** — emit as a `/spec` Boundaries-style
   **key-bullet block** (mirrors `skills/spec/SKILL.md` §Boundaries
   format). Fixed-width kind label padded to 8 chars, `·`-bulleted
   entries underneath, **one fact per bullet**. Skip the kind row
   entirely if zero entries — never emit a label with empty body.

   ```
     State    · {one-line fact}
              · {one-line fact}
     A11y     · {feature-specific a11y item}
              · {feature-specific a11y item}
     Wiring   · {clean or informational multi-point note}
   ```

   **State** — schema/state shape; reference the ADR that locked it.
   **A11y** — feature-specific only (UI features), per the internal
   checklist; no universal WCAG. **Wiring** has three mutually exclusive
   cases:
   - Clean → `Wiring   · no extra registration needed.`
   - Informational multi-point → kind+bullet, no `⚠`.
   - Has a finding → emit the `⚠` card below directly. **Do not also
     emit a `Wiring` labeled line.** The card title `⚠ Wiring — {topic}`
     IS the label.
3. **`⚠` finding cards** — only for findings that need the full
   Problem/Impact/Fix/Severity breakdown. A simple wiring note doesn't.

**Do NOT emit a top-of-§3A verdict line** (`Architecture: 1 wiring note. No
security findings.`). The REVIEW summary at the top of Phase 3 already
carries that verdict — restating it inside §3A is duplicate.

**Do NOT emit a `Wiring` stub line that points at a card below**
(`Wiring: ⚠ CRITICAL — see finding below.`). The card title is the label;
a stub is duplication. This is the third duplication path after the
top-of-§3A verdict and the multi-card-where-inline-suffices.

#### 3B · Error handling

**Internal reasoning (do NOT output pattern guidance):**

- Catch-all exceptions are a smell — name specific ones.
- Swallow-and-log is almost never acceptable.
- LLM/AI calls must handle: malformed, empty, refusal, hallucinated JSON.
- Every caught error must: retry with backoff, degrade gracefully, or re-raise.

**Enumerate every new API endpoint and codepath, then assess failure modes.**
This is a forcing function — think through what can fail at each codepath
before concluding whether gaps exist.

**Output only rows where errors are NOT caught or NOT handled properly:**

| Codepath | Failure | Caught? | User Sees |
|----------|---------|---------|-----------|
| {path} | {failure} | **N ← GAP** | 500 / silent |

> Any row with **Caught=N** → **CRITICAL GAP** — must be resolved before TDD.

After the table: `Assessed {N} codepaths. {M} gaps found.`

If all error paths are handled: `✓ Error handling: assessed {N} codepaths, no gaps.`

**Code-quality issues** — output only if found (DRY violations, naming, over/under-engineering).

#### 3C · Test coverage

**Internal reasoning (evaluate all; output only gaps):**

Coverage categories:
- New UX flows (happy + failure + edge)
- New data flows (happy + failure + edge)
- New codepaths (happy + failure + edge)
- Background jobs
- New integrations
- Error paths from §3B

Edge case scenarios:
- Idempotency — double-submit, duplicate job execution, retry while in-flight
- State conflicts — navigate-away mid-action, stale state, optimistic update races
- Result shape — zero / empty, large (10k+), results change mid-page
- Partial completion — jobs, multi-step flows

**Output only gaps that need test coverage. One unified table:**

| # | Type | What's not tested / Scenario | Why it matters / Expected behavior |
|---|------|------------------------------|------------------------------------|
| 1 | gap | {gap} | {reason} |
| 2 | gap | {gap} | {reason} |
| 3 | edge | {scenario} | {expected behavior} |

`Type` is `gap` (coverage missing) or `edge` (boundary scenario). Don't emit
two separate tables — readers shouldn't context-switch between schemas for
adjacent items.

If all paths have adequate coverage: `✓ Test coverage: no gaps identified.`

> **Confidence check:** What test would make you confident shipping at 2am Friday?

#### 3D · Performance & deployment

**Internal checklist (output only concerns):**

- Query hot spots — N+1, missing indexes, unbounded result sets, top 3 slowest codepaths
- Migration — backward compatibility, zero-downtime, deploy-order dependencies
- Rollout — old+new code running simultaneously, feature flag coverage

If concerns exist:

```
⚠ Performance: {concern} — {impact and recommendation}
⚠ Deployment: {concern} — {impact and recommendation}
```

If no concerns: `✓ Performance & deployment: no concerns.`

When perf has a concern but deployment is clean (or vice-versa), still
acknowledge the clean half on its own line — don't let silence imply absence
of review. e.g.: `⚠ Performance: …` followed by `✓ Deployment: no concerns.`

#### Review → TDD plan transition

After §3D, the review flows directly into the TDD plan section. No gate
between them. Critical findings from the review are carried forward into
the single gate at the end of the TDD plan.

#### 2e · TDD plan — test execution order + single gate

> **TDD is mandatory.** Write failing tests first, then implement to pass, then refactor.
> This section produces the test-first execution plan and the single gate.

#### 2f · TDD header (Overview + Risks above test order)

```
▎ ★ THE OVERVIEW
▎
▎ {1–2 plain-English lines: how many tests, grouped by area.
▎ E.g., "23 tests across context, router, rail, drawer, mobile, provider, registry, lifecycle, visual."}

▎ ⚠ TEST PLAN RISKS
▎
▎ • {plan-level risk — largest regression surface, hardest harness need, etc.}
▎ • {2–3 bullets max}
```

#### 2f-ii · TDD receipts — between header and gate

**Test strategy** (one line based on scope):

- Single module → Classic TDD (unit tests first per function)
- Multi-module → ATDD (acceptance tests from spec criteria first, then units)
- API/service → Contract tests first (request/response shapes), then implementation
- UI feature → Component behavior tests first (from `/design` states), then implementation
- Bug fix → Regression test first (reproduces the bug), then fix

**Default — compact TDD list:**

```
TDD ({N} tests)
  1. {test-file} → {what it verifies, AC or gap ref}
  2. {test-file} → {what it verifies}
  ...
```

One line per test. No Test type or Derives from columns — the AC/gap
reference is inline. The TDD header (overview + risks) is also suppressed
by default. User can surface the full table via `receipts eng`.

**Verbose mode — full test-first execution order:**

| Order | What to test first | Test type | Derives from |
|-------|-------------------|-----------|--------------|
| 1 | {acceptance test from spec criteria} | Integration / E2E | AC-{N} |
| 2 | {contract test for new API/service} | Contract | §2 |
| 3 | {unit test for core business logic} | Unit | §2 |
| 4 | {unit test for error handling} | Unit | §3B |
| 5 | {edge case tests} | Unit | §3C-{n} |

**Sub-grouping rule:** if the table exceeds ~12 rows, insert a one-line
header above each group (`Context · 1–3`, `Mode router · 4–6`, etc.) — the
table stays a single table, but the reader can scan by area. Don't split
into multiple tables.

**`Derives from` column rule:** use anchors, not spelled-out tokens.
✓ `AC-5 · §3A WARN · gap 4`. ✗ `AC-5 · §3A WARNING · §3C gap 4`. Three-line
wraps in this column are a smell — tighten the anchors.

**Rules:**
- Every gap from §3C MUST have a test entry.
- Tests derive from spec ACs (if `/spec` ran) or from §3 findings.
- Each test must be writable **without** the implementation existing — test the interface, not the internals.
- Error-path tests are not optional — include every CRITICAL GAP from §3B.
- **No placeholders.** Every entry names the specific function/endpoint/component,
  exact input scenario, and expected outcome. "Test user creation" is not
  acceptable — "Test POST /users with valid email returns 201 and user object
  with id" is. The implementer should write the test from this entry alone.
- **Code objects belong in test files, not table cells.** Describe the
  contract in prose; reserve literal code for the test source. ✗ Cramming a
  full `registerTab({...})` object into the description column.

**Test infrastructure** (always emit a one-liner — don't go silent):

```
  Infra: {adequate | needed: matchMedia mock, focus-trap-react, swipe-gesture sim, …}
```

If adequate, say so explicitly. Silence on infra is not a pass.

#### 2g · GATE — at the bottom, after all receipts

Emit immediately after the test infrastructure line. This is the ONLY gate
in `/eng` — it covers overview, review findings, and TDD plan approval.

**When `/eng` is downstream** (HANDOFF present, `Verbose: true` absent):
gate is suppressed. Use P2 (architecture) to select the approach if
`Principles:` is present: minimal → smallest-diff option; balanced →
recommended option; ideal → best-architecture option. Without `Principles:`,
use the recommended option.
If scope spans 8+ files or independent areas, **always route to `/swarm plan`**
instead of `/tdd`. In **autonomous mode** (HANDOFF present, `Verbose: true`
absent): emit a transition line and `HANDOFF → /swarm` (auto-chain continues).
In **interactive mode**: stop and present the swarm recommendation to the user.
Swarm-eligible scope must use swarm regardless of P3.
If the scope guard fires for other reasons, check P3 (risk): aggressive →
proceed with a note in the transition line; moderate/conservative → escalate.
Emit a transition line instead of the gate:

```
══ /eng · Approach {letter} — {summary} · {N} tests planned ════════════════════
```

When swarm-eligible scope detected, the transition line names swarm:

```
══ /eng · Approach {letter} — {summary} · {N} files / {M} areas → /swarm ══════
```

**When `/eng` is the entry point** (user invoked directly) or `Verbose: true`:

```
▎ ▸ GATE — approve plan?
▎
▎ Overview: {approach letter} — {one-line summary}
▎ Review:   {N} critical · {N} gaps · {N} test gaps
▎ TDD:      {N} tests planned
▎
▎ Reply "go" to proceed (lean output, auto-chain to /tdd → /review → /ship).
▎ Reply "go verbose" for full receipts and per-skill gates.
▎ Or override any section.
▎ Next: /hashb:tdd (recommended — execute test cycles)
▎       {OR: /hashb:swarm plan (recommended — {N} files across {M} areas) when swarm-eligible scope detected}
▎ After any skill: "receipts" to expand suppressed detail.
```

The gate summarizes all three sections (overview, review, TDD plan) in a
compact block.

### Phase 3 · Summary

Phase 3 re-emits the **full progress block** at the start of the phase.

```
/eng ═════════════════════════════════════════════════════════════════════════════════

  ✓ Phase 1  Impact Map
  ✓ Phase 2  Plan
  ▸ Phase 3  Summary

══════════════════════════════════════════════════════════════════════════════════════
```

Single template (works for arch + impl or impl only). **Bold** the critical
fields the reader scans for; omit empty rows.

```
✓ ENG · {system} · {mode} · {N ADRs if any} · {N risks}
  Scope:       {accepted | reduced}
  Findings:    arch {N} · errors {N} **GAPS** · tests {N} · perf {N}
  Critical:    **{list or "none"}**
  ADRs:        {list of ADR titles if any, else omit row}
  TDD order:   1. {test} → {impl}
               2. {test} → {impl}
```

**No `Next:` row in Phase 3.** The gate already named the next-step skill,
and `go` auto-chains immediately — restating `Next:` here is redundant
because the downstream skill's Phase 1 banner emits right below this
summary. (If the user replied `stop`, they explicitly chose not to chain;
the gate prompt that named the recommendation is still in scrollback.)

**Task badge** — if the handoff includes a `Task:` line (from `/decompose`),
append `[eng ✓]` to the task's badge line in the TODOS file. If the task
has no badge line yet, create one (continuation line, indented 6 spaces).
Skip if `[eng ✓]` is already present. Update the root index count if needed.

**Tracker badge label** — if `TRACKER_TYPE=github-issues` (see
`skills/shared/tracker.md` §Badge Label Block), also add the `hashb:eng` label
to the GitHub Issue matching the task number. Skip silently on failure — the
local badge is the in-session source of truth; the label syncs for
cross-session visibility.

**Open items** — emit only if non-empty:

| Category | Item | Rationale |
|----------|------|-----------|
| Not in scope | {deferred} | {one-line why} |
| Unresolved | {unanswered decision} | {never silently default} |

**Swarm recommendation (mandatory)** — if scope spans 8+ files or multiple
independent areas, always route to `/swarm plan`. This is not optional.
When `/eng` is the **entry point** (or `Verbose: true`), the gate's `Next:`
line MUST lead with `/hashb:swarm plan (recommended — {N} files across {M}
areas)` and present the recommendation to the user.
When `/eng` is **downstream** (HANDOFF present, `Verbose: true` absent),
emit the transition line and `HANDOFF → /swarm` — the chain continues
autonomously into `/swarm`.

---

## Inferred Spec Write

When no `specs/{slug}.md` exists for the current scope (i.e., `/spec` was
skipped), write one after the gate is approved. This gives `/review` and
`/qa` structured ACs to verify against across sessions.

**Derive ACs from existing analysis:**
- User request → primary goal as AC-1 (MUST)
- §3B CRITICAL gaps → error-handling MUST ACs
- §3C coverage gaps → behavior MUST/SHOULD ACs
- §3D user-observable perf concerns → SHOULD ACs
- Cap at 7 ACs. Merge related ones.

**File format — identical to `/spec` output, different source:**

```markdown
# {Capability Name}

> Last updated by /eng on {YYYY-MM-DD}
> Source: engineering-inferred

## Acceptance Criteria

- **AC-1:** (MUST) {user-facing summary}
  - GIVEN {precondition} WHEN {action} THEN {outcome}
- **AC-2:** (SHOULD) {user-facing summary}
  - GIVEN {precondition} WHEN {action} THEN {outcome}

## Boundaries

- **Constraint:** {limit}
- **Assumption:** {premise}
- **Out of scope:** {item} — {reason}
```

**Rules:**
- Never overwrite a `product-authored` spec.
- If `specs/` doesn't exist, ask the user before creating (same rule as `/spec`).
- Slug: kebab-case from the capability name in THE OVERVIEW. If upstream
  HANDOFF includes `Spec file:`, use that slug.
- GWT clauses may be more implementation-flavored — that's fine. Same
  structure, different precision.

---

## Handoff Summary

After the summary, emit a compact handoff block for `/tdd`. This is what
`/tdd` consumes — it does NOT re-read the full `/eng` output from
conversation context.

```
HANDOFF → /tdd
  Scope:       {one-line what's being built}
  Approach:    {letter} — {one-line summary}
  TDD order:   {N} tests — {strategy from §2f}
  Review:      {N} critical · {N} gaps (addressed in TDD plan)
  Principles:  {forwarded from upstream HANDOFF, if present}
  Verbose:     true                          ← only if user said "go verbose"
  Spec file:   specs/{capability-name}.md
  Task:        #{N} in {file}               ← only if /decompose task is being executed
  Risks:       {top 2 risks, one line each}
```

Rules:
- Total handoff: ≤10 lines.
- TDD order carries the count and strategy, not the full table.
- `Principles:` line: forward from upstream HANDOFF if present.
- `Verbose:` line: forward from upstream HANDOFF if present. Omit by default.
- `Spec file:` is unconditional — the file always exists after `/eng`
  (either product-authored from `/spec` or engineering-inferred).
- `Task:` line: if `/eng` is executing a `/decompose` task, forward the task
  number and its TODOS file (e.g., `#3 in specs/auth.todos.md` or
  `#7 in TODOS.md`). `/tdd` uses this to mark the task `[x]` on completion.
  Omit when `/eng` was invoked standalone (no decompose context).
- `/tdd` reads this handoff + the spec file for AC details.

**When swarm-eligible scope is detected (8+ files or independent areas):**

```
HANDOFF → /swarm
  Scope:       {one-line what's being built}
  Approach:    {letter} — {one-line summary}
  File inventory: {N} files across {M} independent areas
  Impl order:  {prerequisite → parallel streams ordering from §2b}
  Review:      {N} critical · {N} gaps
  Principles:  {forwarded from upstream HANDOFF, if present}
  Verbose:     true                          ← only if user said "go verbose"
  Spec file:   specs/{capability-name}.md
  Risks:       {top 2 risks, one line each}
```

Rules:
- Same ≤10-line budget as the `/tdd` handoff.
- `File inventory` and `Impl order` replace `TDD order` — swarm needs
  file counts and ordering, not test strategy.
- `/swarm` reads this handoff to populate §Inputs (scope card, file
  inventory, implementation order) without re-reading the full `/eng` output.

---

## Next step

| Condition | Next |
|---|---|
| Scope spans 8+ files or independent areas | **`/swarm plan`** (always — interactive: stop and present; autonomous: auto-chain with `HANDOFF → /swarm`) |
| Standard feature (< 8 files, single area) | `/tdd` → `/review` |
| Need to scaffold a module first | `/module` → `/tdd` |
| Implementation complete | `/review` |

**Swarm-first rule:** swarm-eligible scope always routes to `/swarm plan`,
never to `/tdd` directly. This applies in all modes. In interactive mode,
stop and present the recommendation. In autonomous mode (HANDOFF present,
`Verbose: true` absent), emit transition line + `HANDOFF → /swarm` and
auto-chain.

**Default chain (non-swarm):** auto-invoke `/tdd` using §4 TDD order.
After `/tdd` completes, auto-invoke `/review`. If `/review` returns
APPROVED, auto-invoke `/ship`. Follow gate rules in `skills/shared/formatting.md`.

---

## Gather Context (appendix)

Branch/base detection: see `skills/shared/preflight.md`. Beyond that, the
standard minimal bash:

```bash
git log --oneline -15
git diff $(git merge-base HEAD "${BASE:-main}")..HEAD --stat
grep -r "TODO\|FIXME\|HACK" -l --exclude-dir={node_modules,vendor,.git,dist,build} . | head -20
```

Read if present: `CLAUDE.md`, `TODOS.md` (root index + General section),
`specs/*.todos.md` (per-spec task files referenced from the root index),
`docs/designs/`. Check Claude Code memories for relevant retro findings.

---

## Rules

| Rule | Why |
|------|-----|
| Read-only (except `specs/`) | No code changes. ADRs inline; user decides where to save. Writes inferred spec to `specs/{slug}.md` when no spec file exists — see §Inferred Spec Write. |
| One gate (entry-point) | Single gate after overview + review + TDD plan. Downstream: gate suppressed, emits transition line. Small emits one response. |
| Inverted-pyramid output | Decision-grade summary (4 `▎` blocks); receipts (file tree, approach, ADRs, review, TDD plan) below `══` separators; single gate at bottom. See `skills/shared/formatting.md`. |
| Handoff summary after gate | Emits a compact handoff block for `/tdd`. See §Handoff Summary. |
| Internal reasoning, signal-only output | Checklists run internally. Output only findings — no "ok" rows. |
| Plain English in prose | Use the simplest words a working engineer would use mid-task. Keep technical precision for code identifiers, file paths, CSS units, breakpoints, version numbers. See `skills/shared/formatting.md`. |
| Be opinionated | Recommend one option. "It depends" is not engineering. |
| TDD is mandatory | Every implementation has a test-first plan. No exceptions. |
| Runtime wiring always surfaces | Surface it even when all other checks pass — compile-but-fail-at-runtime is load-bearing. |