Grill

---
description: >
  Architecture fitness evaluation — optional, on-demand skill that challenges existing
  architecture and engineering decisions. Produces a scored report with ROI-ranked
  refactoring recommendations. Adversarial posture: challenges rather than describes.
  Systematically finds blindspots and loopholes. Prefers .understand/architecture-map.md
  as starting point but runs standalone if missing. Read-only.
argument-hint: "[scope or subsystem path]"
---

# Grill

Challenge the architecture and engineering decisions of an existing codebase.
Produce a scored fitness report with ROI-ranked refactoring recommendations.

**Writes `.grill/grill-{date}.md` only. No code changes.**

**This skill is OPTIONAL and on-demand.** It is never a required step in any recipe.
Users invoke it deliberately when they want an architecture fitness evaluation.

---

## When to Use

| Signal | Why grill? |
|--------|------------|
| "Is our architecture still fit for purpose?" | This is the core question grill answers |
| "Are we over-engineered?" | Simplicity audit identifies unjustified abstractions |
| "Should we refactor X?" | ROI matrix ranks which debts to pay down first |
| Before a major refactoring initiative | Challenge decisions before redesigning |
| Quarterly or annual architecture review | Periodic health check on the foundation |
| After significant growth (team, traffic, features) | Check whether original decisions still hold |
| Onboarding to a brownfield codebase (optional follow-up to `/understand`) | Go beyond mapping to evaluation |

**Don't use when:**
- You want a map of what exists — use `/understand`
- You want hashb rule compliance scoring — use `/audit`
- You want to design a new subsystem — use `/eng arch`
- You want to review code on a diff — use `/review`
- You want to simplify a specific file — use `/simplify`
- You have a specific question to investigate — use `/explore`

---

## Hard Boundaries

| Does NOT | Delegated to |
|----------|--------------|
| Do exhaustive architecture mapping | `/understand` (preferred upstream; grill builds minimal inventory if absent) |
| Score hashb rule compliance | `/audit` |
| Design the replacement architecture | `/eng arch` (handoff) |
| Review code-level quality on a diff | `/review` |
| Apply code simplification | `/simplify` (handoff) |
| Modify any files (other than `.grill/` report) | — |

**Core principle:** Grill surfaces decisions worth revisiting and estimates ROI.
It does NOT design the replacement. That is `/hashb:eng arch`'s job, fed by this skill's findings.

**Evidence principle:** Grill gathers its own evidence when it needs it. `/understand`'s
map is a starting point, not a ceiling. When a pass's claim rests on a stale or
missing map entry, grill reads the code, queries the graph, or runs git log
directly. No pass ships a conclusion that depends only on an unverified map entry.

---

## Execution Flow (MANDATORY)

> **This is the ONLY valid sequence. Never skip or reorder phases.**
> Each gate marked **STOP** requires completion before proceeding.

```
┌─────────────────────────────────────────────────┐
│ Phase 0: Prerequisites + MCP detect             │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 1: Inventory (map + graph verification)   │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 2: Grill (6 evaluation passes, incl. F)   │
└────────────────────┬────────────────────────────┘
                     │
              ■ STOP │ User reviews raw findings before synthesis
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 3: Synthesize (Fowler quadrant + ROI)     │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 4: Report                                 │
└────────────────────┬────────────────────────────┘
                     │
              ■ STOP │ User reviews final report
```

Max 2 gates. Single session.

---

## Presentation Rules

1. **Wizard flow** — present one phase at a time. Never dump everything at once.
2. **Gate placement** — both gates (Phase 2 mid-skill, Phase 4 final) emit at the BOTTOM of their phase output, after raw findings / final report respectively. The reader has context to decide without scrolling back up.
3. **Progress indicator** — every output starts with the block below; **re-emit the full block at the start of any phase that contains a gate** (Phase 2 and Phase 4):

```
/grill ══════════════════════════════════════════════════════════

  ▸ Phase 0    Prerequisites
  ○ Phase 1    Inventory
  ○ Phase 2    Grill (6 passes)
  ○ Phase 3    Synthesize
  ○ Phase 4    Report

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

Update `▸` (current), `✓` (done), `○` (pending) as phases progress.
Completed phases show a status note on the right (e.g., `✓ 7 modules`, `✓ 6 passes`, `✓ {N} findings`, `✓ {score}/100`).

Also follow the shared formatting rules in `skills/shared/formatting.md`.

---

## Phase 0: Prerequisites

### Required Input

```bash
# The architecture map from /understand is a hard prerequisite.
ls .understand/architecture-map.md 2>/dev/null

# Project Profile for quality-attribute scenario selection
cat CLAUDE.md 2>/dev/null | head -80

# Existing ADRs (optional — enables Assumption Freshness pass)
ls -d docs/adr/ docs/adrs/ adr/ 2>/dev/null
ls docs/adr/*.md adr/*.md 2>/dev/null
```

### Prerequisite Gate

`/understand`'s map is a **starting point, not a ceiling**. Trust but verify —
spot-check the map against current code, and gather additional evidence when a
pass needs it (direct file reads, git log, or graph queries). Do not refuse to
run because an upstream artifact is missing or stale.

| Condition | Action |
|-----------|--------|
| `.understand/architecture-map.md` exists and is current | Use as starting point. Spot-check with graph queries or file reads where a pass needs more resolution. |
| Map exists but is stale (> 30 days old) | Warn user. Proceed but verify aggressively via graph queries and direct code scan. Treat map entries as hypotheses, not facts. |
| `.understand/architecture-map.md` missing | Proceed in **standalone mode**. Build minimal inventory via graphify MCP (if available) or direct code scan (module dirs, entry points, dependency manifests). Label report "Standalone — no architecture map." Never refuse. |
| Map contradicts observed code | Record the contradiction as a finding (Inadvertent + Reckless — the map is lying to the team). Trust current code. |
| No Project Profile | Proceed with degraded scenarios. Flag in report. |
| No ADRs found | Proceed. Assumption Freshness pass runs in "infer from code" mode. |

### Graphify MCP Integration

When the graphify MCP server is available, grill uses it to gather evidence
directly — not just to speed up `/understand`'s job. The graph provides
live, structural truth that a map may have drifted from.

Detect availability (same pattern as `/understand`):

```bash
python -c "import graphify; print('graphify installed')" 2>/dev/null || echo "not installed"
```

Check for `mcpServers.graphify` in Claude config. If configured, tools available:
`query_graph`, `get_node`, `get_neighbors`, `get_community`, `god_nodes`,
`graph_stats`, `shortest_path`.

| MCP Tool | Which Pass | Purpose |
|----------|------------|---------|
| `get_community` | C, F | Verify module boundaries vs. the map; detect communities the map omitted |
| `god_nodes` | C, F | Identify coupling hotspots directly — no reliance on map's coupling field |
| `get_neighbors` | C, E, F | Trace actual dependency direction per module; verify ADR coupling claims |
| `shortest_path` | C, F | Detect circular dependencies and unexpected inter-module links |
| `graph_stats` | C, F | Overall density / modularity metrics — sanity-check the map's scale claims |
| `query_graph` | F | Open-ended structural queries for blindspot detection |

**Budget:** Max 8 MCP queries total across all passes (3 more than `/understand`
because grill evaluates, not just describes). Reserve at least 2 for Pass F.
If `code-review-graph` MCP is also available, same budget counts both combined.

**If graphify is unavailable:** All passes run in standard mode — direct file
reads, grep, git log. Label affected findings "evidence: file read" so the user
can judge confidence. Do not refuse.

### Scope Card

Present before proceeding:

```
GRILL ──────────────────────────────────────────────────────────

  Repo             {name}
  Date             {date}
  Map source       {.understand/architecture-map.md (generated date) | standalone}
  Profile          {Architecture | Platform | Stack from CLAUDE.md — or "none"}
  ADRs             {count — or "none found"}
  Modules          {N from map | N from graphify | N from directory scan}
  Focus            {full system | user-specified subsystem}
  MCP              {graphify available — graph-accelerated | not configured | not installed}

  MODE: {map-guided | standalone | hybrid}

─────────────────────────────────────────────────────────────────
```

No gate. Proceed to Phase 1.

---

## Phase 1: Inventory

Build the Architecture Inventory from the map and codebase.

### Enumerate

For each module in the architecture map, collect:

| Column | Source |
|--------|--------|
| Module | From architecture map Module Boundaries |
| Declared pattern | From Project Profile Architecture field |
| Detected patterns | From convention detection — read 2-3 representative files per module |
| Dependencies | From architecture map Key Dependencies |
| Coupling level | From architecture map Coupling & Risk Areas |
| Age signal | Git history — first commit date, last substantive change |

Budget: max 5 files per module. Sample, don't exhaustively scan.

### Inventory Table

```
ARCHITECTURE INVENTORY
─────────────────────────────────────────────────
| Module | Pattern | Deps | Coupling | Age |
|--------|---------|------|----------|-----|
| {name} | {pattern} | {count} | {H/M/L} | {months} |
```

No gate. Proceed to Phase 2.

---

## Phase 2: Grill (6 Evaluation Passes)

> **All six passes are mandatory** unless prerequisites are missing (e.g., no ADRs).
> Skip a pass only by explicitly marking it "SKIPPED: {reason}" in the report.

> **Evidence discipline (I1, I8):** Each pass gathers its own evidence — don't
> stop at what the map says. If a pass's claim rests on a map entry that can't
> be re-verified against code or graph, label it `Inferred` or `Unverified`,
> not `Verified`.

See `references.md` for detailed per-pass checklists, signals, and scoring rubrics.

### Pass A — Simplicity Audit (Karpathy-inspired)

Challenge unjustified complexity. For each abstraction layer ask: "Is this justified
by actual variation, or is it speculative extensibility?"

**Countable signals** (every finding must cite a concrete signal, not vibes):

| Signal | What it suggests |
|--------|-------------------|
| Interface with 1 implementation | Speculative abstraction |
| Generic type instantiated with 1 concrete type | Speculative extensibility |
| Plugin/strategy system with 1 plugin | Speculative extensibility |
| Factory returning a single type | Unjustified indirection |
| Abstract class with 1 subclass | Premature abstraction |
| Wrapper functions that only call through | Accidental indirection |
| Configuration for values that never change | Speculative configurability |
| Layers beyond what the problem demands | "Layer cake" over-engineering |

**Senior Engineer Test per module:** "Would a senior engineer joining today say
this is overcomplicated for what it does?"

Record findings with file:line evidence.

### Pass B — Structural Fitness (ATAM-lite)

Define 3–5 quality-attribute scenarios derived from Project Profile. For each,
trace through the architecture: does the current structure support this well,
poorly, or not at all?

See `references.md` for scenario templates per stack (SaaS, CLI, API-only, library,
mobile, embedded).

**Per-scenario output:**

| Scenario | Support | Sensitivity Point | Trade-off |
|----------|---------|-------------------|-----------|
| {scenario} | {well/poor/none} | {where small changes cascade} | {what improving this would cost} |

### Pass C — Coupling / Cohesion Assessment

Go beyond `/understand`'s descriptive coupling map to evaluate: is this coupling
level *appropriate*?

| Check | Signal |
|-------|--------|
| Modules coupled but serving unrelated concerns | Should split |
| Modules decoupled but always changing together | Should merge (shotgun surgery) |
| God modules | Architectural hotspot, likely refactor target |
| Circular dependencies | Boundary violation |
| Dependency direction violations (e.g., domain → infrastructure) | Inverted dependency |
| Cross-module DB access | Leaky boundary |
| Public API surface disproportionate to module size | Missing encapsulation |

### Pass D — Technology Fit

For each major dependency / framework, evaluate fit against current constraints.

| Check | Signal |
|-------|--------|
| Over-powered tool for the problem | e.g., enterprise framework for CRUD app |
| Under-powered tool for the scale | e.g., SQLite for multi-tenant SaaS at scale |
| Deprecated / abandoned dependency still load-bearing | Hidden debt |
| Multiple libraries solving the same problem | Inconsistency, duplicate maintenance |
| Build/toolchain complexity disproportionate to app complexity | Meta-complexity tax |

If Context7 MCP is available, check deprecation status and current best practices
for each major dependency. Max 3 queries total.

### Pass E — Assumption Freshness

Challenge the original assumptions behind architectural decisions.

**If ADRs exist:** For each ADR, check whether the "Context" section is still true.
Flag ADRs where the stated constraint has changed (team size, scale, tech landscape,
business model).

**If no ADRs exist:** Infer likely original assumptions from the architecture itself.
Mark pass as degraded: "No ADRs — assumptions inferred from code structure, speculative."

| Assumption Type | Example |
|-----------------|---------|
| Scale assumption | "Designed for ~100 users" — is that still true? |
| Team assumption | "Designed for solo developer" — is the team now 10? |
| Tech assumption | "Designed when X library was the standard" — still is? |
| Business assumption | "Designed for single-tenant" — now multi-tenant? |

### Pass F — Blindspot & Loophole Detection

Passes A–E challenge *what is visible*. Pass F systematically surfaces *what is
not visible* — design holes, silent failure paths, implicit contracts, and
coupling that doesn't show up in the import graph. Every other pass relies on
reading the architecture; this one reads its shadow.

**Required. Never skipped.** Blindspots are where incidents start.

This pass gathers evidence directly. Do not satisfy with map or ADR contents —
verify against code, config, tests, and graph queries.

**Ten blindspot categories** (all are mandatory checks — report only categories
with findings, but trace each one before reporting):

| # | Category | What to look for | Countable signal |
|---|----------|------------------|------------------|
| 1 | **Trust boundaries** | Untrusted input crossing into trusted code without validation | Grep entry points; trace each to first typed/validated boundary. Gap = finding. |
| 2 | **Implicit contracts** | Callers must satisfy undocumented preconditions (order of calls, prior state, env vars) | Scan for `assert` / `if not initialized` / "must call X first" comments; check public API docs |
| 3 | **Non-obvious coupling** | Modules coupled via shared state, global config, DB rows, files, env, or temporal ordering — not imports | `god_nodes` on shared resources; grep for singletons/globals; check DB tables written by > 1 module |
| 4 | **Single points of failure** | Components whose failure cascades with no graceful degradation | Trace one critical flow; identify each dependency; check for retry/fallback/circuit breaker |
| 5 | **Concurrency hazards** | Race conditions, shared mutable state, missing locks, reentrancy | Grep for thread/async/worker patterns; check shared state writes; look for check-then-act sequences |
| 6 | **Silent failure paths** | Errors swallowed, defaulted, or logged-but-continued without user impact surfaced | Grep `catch.*pass`, `except: pass`, `\|\| null`, `.catch(() => {})`; trace error paths |
| 7 | **Observability gaps** | Failures that occur with no trace — no log, metric, or alert | For each critical flow: is success counted? Failure counted? Latency measured? Gap = finding. |
| 8 | **Deletion & cascade paths** | Removing a record / tenant / user leaves orphans, dangling refs, or invalid state | Grep `ON DELETE`; check every FK; trace what happens on resource removal |
| 9 | **Recovery paths** | What happens *after* a failure — is there a documented path back to healthy state? | Check for idempotency, replay, dead-letter queues, manual recovery scripts |
| 10 | **Scaling cliffs** | Load pattern where performance degrades non-linearly (N², exponential, lock contention) | Look for nested loops over unbounded inputs, unindexed queries, fanout without backpressure |

**Systematic traversal — not ad-hoc:**

For each category, follow this procedure:

1. **Scope** — name the category and the area of code to examine (module / flow / resource).
2. **Evidence gathering** — grep + read + (graph query if available). Record what was checked.
3. **Signal or clear** — either cite a countable signal (file:line + pattern), or state "no signal found" explicitly. No silent passes.
4. **Severity** — CRITICAL if exploitable or load-bearing; HIGH if likely incident trigger; MEDIUM if latent risk; LOW if theoretical.

**Blindspot output per finding:**

```
⚠ BLINDSPOT: {category} — {one-line summary}

  Where       {file:line or module}
  Evidence    {what was checked, what was found — cite signal}
  Risk        {what incident this enables}
  Hidden by   {why it escapes the other five passes — e.g., "not in import graph", "no ADR", "only triggered under concurrent load"}
  Severity    CRITICAL | HIGH | MEDIUM | LOW
```

**Loophole detection (paired with blindspots):**

A loophole is where a rule, invariant, or boundary *can* be violated even if it
currently isn't. Every declared invariant in the codebase has an implicit loophole
check: can an adversarial caller, a race, a retry, or a new feature bypass it?

| Invariant type | Loophole check |
|----------------|----------------|
| "Data is always validated before insert" | Find every insert path — is every one guarded? |
| "Tenant A never sees tenant B's data" | Every query, cache key, log line — is tenant_id enforced? |
| "This operation is idempotent" | Replay the same input twice — does state diverge? |
| "This can only be called by authenticated users" | Every entry point — is auth enforced before effect? |
| "Rate limit prevents abuse" | Is the limit per-IP? Per-user? Per-tenant? Can it be sidestepped? |
| "Transaction rollback is atomic" | Side effects outside the transaction (logs, events, external calls)? |

Report loopholes using the Blindspot format above, labeled `Category: Loophole`.

### Phase 2 Gate

> **STOP.** Present raw findings before synthesis.
>
> "Here are the raw findings from each pass. Before I synthesize and compute ROI,
> are there findings you want to override, dismiss as known trade-offs, or add
> context to?"

User may:
- Dismiss findings as deliberate trade-offs (mark "deliberate-prudent" in synthesis)
- Add context that changes severity
- Flag findings as blockers (force top of report)

---

## Phase 3: Synthesize

### Fowler Debt Quadrant Classification

Every finding is classified on two axes:

```
                    Deliberate           Inadvertent
                ┌─────────────────┬──────────────────┐
      Prudent   │ Known trade-off │ Honest learning  │
                │ (accept or plan)│ (fix when ready) │
                ├─────────────────┼──────────────────┤
    Reckless    │ Tech debt by    │ Carelessness     │
                │ choice (justify)│ (fix soon)       │
                └─────────────────┴──────────────────┘
```

See `references.md` for classification heuristics.

### ROI Scoring

For each finding:

| Axis | Values | Meaning |
|------|--------|---------|
| Effort | S / M / L | Rough refactoring cost (hours / days / weeks) |
| Value | H / M / L | Risk reduced + delivery unblocked |
| ROI rank | Derived | Sort: high-value + low-effort first |

> **AI-estimated effort is unreliable.** Label the Effort column explicitly as
> "rough estimate, validate with team before prioritizing."

### Fitness Scoring

Each pass scores 0–100. Deduction rubric in `references.md`.

- **Simplicity** — 100 − (N unjustified abstractions × weight)
- **Structural** — 100 − (N scenarios with poor/none support × weight)
- **Coupling** — 100 − (N coupling violations × weight)
- **Technology** — 100 − (N fitness concerns × weight)
- **Assumption Age** — 100 − (N stale assumptions × weight) or "degraded" if no ADRs
- **Blindspot Coverage** — 100 − (N blindspots/loopholes × weight). CRITICAL findings deduct more heavily.

**Overall** — weighted average (Simplicity 20 %, Structural 20 %, Coupling 20 %,
Technology 10 %, Assumption Age 15 %, Blindspots 15 %).

---

## Phase 4: Report

Write to `.grill/grill-{date}.md`:

```
GRILL REPORT ────────────────────────────────────────────────────

  Repo             {name}
  Date             {date}
  Source           .understand/architecture-map.md ({generated date})
  Architecture     {declared from Profile}
  Modules          {N evaluated}

  FITNESS SCORES
  ─────────────────────────────────────────────────
  Simplicity       {score}/100    {N unjustified abstractions}
  Structural       {score}/100    {N scenario concerns}
  Coupling         {score}/100    {N coupling issues}
  Technology       {score}/100    {N fitness concerns}
  Assumption Age   {score}/100    {N stale assumptions | degraded — no ADRs}
  Blindspots       {score}/100    {N blindspots + loopholes}
  ─────────────────────────────────────────────────
  Overall          {weighted}/100

  TOP FINDINGS
  ─────────────────────────────────────────────────
  1.  [{severity}] {finding} — {recommendation}
  2.  [{severity}] {finding} — {recommendation}
  3.  [{severity}] {finding} — {recommendation}

  REFACTORING ROI MATRIX
  ─────────────────────────────────────────────────
  | Rank | Finding | Debt Type | Effort* | Value | Handoff |
  |------|---------|-----------|---------|-------|---------|
  |  1   | {name}  | {quadrant}| S/M/L   | H/M/L | /eng arch / /simplify |
  |  2   | ...     | ...       | ...     | ...   | ...     |

  * Effort is a rough estimate — validate with the team before prioritizing.

  DECISIONS TO REVISIT
  ─────────────────────────────────────────────────
  1. {decision}
     Why: {reason it should be revisited}
     → /hashb:eng arch  {scope prompt}
  2. ...

  SIMPLIFICATIONS
  ─────────────────────────────────────────────────
  1. {module / layer}
     Signal: {countable signal — e.g., "interface with 1 impl"}
     → /hashb:simplify {target}

  STRENGTHS
  ─────────────────────────────────────────────────
  - {What the architecture gets right — evidence-based}
  - {Keep explicit: deficit-only reports lose credibility}

  Next: /hashb:{recommended-per-finding} (recommended — {finding phrase}){· signal-gated alternatives — only when flagged}

─────────────────────────────────────────────────────────────────
```

### Report Rules

- **Evidence is mandatory.** Every finding must cite a file:line, module, or pattern signal.
- **Strengths section is non-negotiable.** At least 2 strengths must be listed.
- **ROI matrix sorted by rank**, not alphabetical.
- **Handoff column is explicit.** Every actionable finding names `/hashb:eng arch` or `/hashb:simplify`.
- **Target 150–250 lines.** If longer, you are documenting implementation details
  — step back to system-level findings.

---

## Next: line resolution

Grill is opt-in and never auto-proceeds — the `Next:` line is advisory, not chain-driving. The `(recommended — reason)` marker swaps at emit time based on the highest-ROI finding actually surfaced.

| Condition detected | Recommended | Phrase |
|---|---|---|
| At least one decision to revisit (top of ROI matrix) | `/hashb:eng arch` | `design replacement for {top-ROI decision}` |
| No decisions to revisit, but simplifications identified | `/hashb:simplify` | `reduce complexity in {top simplification target}` |
| Only LOW-severity findings | `—` | `architecture healthy — no action needed` (emit no chain) |

Signal-gated alternatives (append on the same `Next:` line **only** when the trigger fired):

- `/hashb:simplify (if {N} simplifications also identified)` — append to `/hashb:eng arch` recommendation when both decisions and simplifications surfaced
- `/hashb:eng arch (if {N} decisions also worth revisiting)` — append to `/hashb:simplify` recommendation when only-simplifications path fired but a decision-level finding also exists at lower ROI
- `re-run /hashb:grill (after changes land)` — append when the user explicitly stated they want to track score trend over time

Examples (canonical form — pick one based on resolved findings):

```
Next: /hashb:eng arch (recommended — design replacement for distributed monolith pattern)  ·  /hashb:simplify (if 4 simplifications also identified)
Next: /hashb:simplify (recommended — reduce complexity in src/payments/)
Next: — architecture healthy — no action needed
```

**Interactive mode (default):** State the top handoff as a recommendation:
"Grill complete. Overall fitness {score}/100. Top recommendation: `/hashb:eng arch` for
{highest-ROI decision}."

**Autonomous mode:** Do NOT auto-proceed. Grill is opt-in by design — the user
initiates, the user decides what to act on.

---

## Rules

| Rule | Why |
|------|-----|
| Prefers `/understand` output, runs standalone if missing | Don't refuse when upstream artifact is absent or stale — gather evidence directly |
| Trust but verify the map | Map entries are hypotheses; verify with graph queries or file reads when a pass needs precision |
| Read-only | Only writes `.grill/grill-{date}.md` |
| Challenge, don't replace | Surface decisions; `/eng arch` designs the replacement |
| Evidence-based | Every finding cites a countable signal, file:line, or graph query — no vibes |
| Pass F is mandatory | Blindspot & Loophole detection is never skipped — the things not in the map are where incidents start |
| Use graphify MCP when available | Graph queries beat grep for structural questions (coupling, cycles, hotspots, blindspots) |
| Include Strengths | Deficit-only reports breed noise and lose credibility |
| ROI-ranked, not alphabetical | Top of report = highest-ROI refactoring opportunity |
| Single session, ≤ 2 gates | Not a multi-day workshop |
| Respect Project Profile | SaaS vs CLI vs library get different quality scenarios |
| Label effort estimates as rough | AI-estimated effort is unreliable — don't pretend otherwise |
| Never auto-invoke | Always user-initiated; never inserted into Feature/Bugfix/Release recipes |
| Idempotent | Re-running produces a new dated report; prior reports preserved |

---

## Common Rationalizations

| Rationalization | Reality |
|-----------------|---------|
| "We already know our architecture has issues — we don't need a report" | Implicit knowledge evaporates between sessions and disagrees across teammates. A scored report is falsifiable evidence that survives staff turnover. |
| "The `/understand` map already covers this" | `/understand` describes. Grill challenges. The map says "Module X has high coupling." Grill says "That coupling is unjustified because Y, and refactoring it has high ROI because Z." |
| "We'll just extend `/audit` instead" | `/audit` scores hashb rule compliance. Architecture fitness is a different question with a different methodology. Blurring them dilutes both. |
| "Effort estimates are too unreliable to include" | They are unreliable, which is why they are labeled as rough estimates. A rough estimate beats no estimate when ranking refactoring priority. |
| "The Senior Engineer Test is subjective" | Yes, which is why every Simplicity finding must cite a countable signal (1 impl, 1 plugin, etc.) rather than pure judgment. The test frames the question; the signal grounds the answer. |
| "We don't have ADRs, so Assumption Freshness is useless" | The pass degrades gracefully to "infer from code." The output is labeled as speculative, but still surfaces assumptions worth challenging. |
| "Grill should be part of every brownfield onboarding" | No. It's opt-in by design. Forcing it on every onboarding is exactly the workflow bloat this skill was scoped to avoid. |