expectation-fit
Menu
Lenses Skills How it works Reports GitHub
GitHub

Code that behaves the way people already expect.

Formerly intent-engineering (0.8.x). The /ie-* skills are now /fit-*. See Upgrading from intent-engineering.

expectation-fit is a Claude Code plugin. Five review lenses name the surprise, score it, and propose a fix. Use it on a plan, a change, or a whole codebase.

Install in Claude Code Latest release
Claude Code 
# in any repo, inside Claude Code
/plugin marketplace add https://github.com/davidteren/intent-engineering
/plugin install expectation-fit

Then run /fit-setup if you want project policy. Defaults work with no config. MIT.

order.rb illustrative snippet 
40def fetch_total
41  total = items.sum(&:price)
42  Cache.write("order-total", total)
43  total
44end
P1 predictability confidence 100 least-astonishment

fetch_total also writes a cache row

Broken expectation: a method named fetch reads. This one writes.

Fix: Move Cache.write to the caller, or rename to cache_total!.

Illustrative finding. Same fields as a real lens report (title, principle, severity, confidence, file, line, fix).

One reviewer per kind of surprise

Each lens reads its own heuristics. Two always run. Three switch on by context. A finding that you cannot tie to a broken expectation is not a finding.

Predictability
always on
Name and behaviour mismatches, hidden side effects, surprising returns, silent failures, preview that does not match the result. least-astonishment · DWIM · WYSIWYG
Convention
code
Reinvented conventions, config where convention exists, one-offs that fight the repo or framework. Reads your CLAUDE.md and AGENTS.md first. convention-over-configuration · framework idiom
Simplicity
always on
Needless abstraction, speculative generality, knobs nobody sets. Also guards against cutting a real requirement. Occam · KISS · YAGNI
Experience
user-facing surfaces
Missing interaction states, controls that lie, form and destructive-action gaps, broken keyboard and focus, accessibility gaps, weak information architecture. HIG · look and feel · UX
Architecture
Rails, Python, Laravel, Express, Phoenix, React
Fat models and controllers, God objects, misused services, callback hell, queries in views, layer leaks. Classifies design patterns against a per-stack catalog. structural quality · design patterns

Run the lenses where the work is

Six skills. Four review contexts, plus setup and PR learnings. Fresh is first config. Upgrade adds missing keys and keeps your notes.

/fit-setup

Set up or upgrade

Wizard for .expectation-fit/. Monolith or multi-repo placement, auto CI sources, severity align, pattern preference, thresholds, and calibrate.

/fit-plan-assist

While planning

An advisory checklist of the principle decisions to get right now. Non-blocking.

/fit-validate-plan

Before coding

Dimensional 0–10 ratings on a plan or spec, plus the design gaps to resolve first.

/fit-review

On a change

Findings by severity on a PR, branch, or local diff. Applies safe verified fixes. Never pushes.

/fit-audit

On a codebase

A posture report: per-dimension scores and the top gaps to fix first.

/fit-from-pr-learnings

After review

Mine PR threads into notes, sources, and severities so the next run enforces what humans already fought for.

Fan out, gate, report

The same loop for validate, review, and audit. Confidence below 75 is suppressed, except a P0 that still has 50 or more.

  1. Select

    Walk up to the nearest .expectation-fit config. Pick the lenses that fit the context.

  2. Fan out

    Each lens runs as a parallel sub-agent against its own heuristics.

  3. Gate

    Merge, dedup, and confidence-gate. Every dropped finding is listed with its reason.

  4. Report

    A ranked report with the broken expectation and a concrete fix for each finding.

Grounded, not vibes

  • A researched knowledge base ships in the plugin: principles, per-framework conventions, and cross-cutting topics. Each has a violation-smell checklist and cited sources.
  • Confidence anchors are 0, 25, 50, 75, and 100. Findings gate at 75. Critical surprises survive lower.
  • When two principles conflict, the lens names the tension and presents the trade-off. It does not dictate.

Tunable and read-only

  • .expectation-fit/ config walks up from the working directory. Project values override plugin defaults.
  • Read-only by default. Only /fit-review applies gated_auto fixes locally, and it never pushes.
  • A contract suite runs in CI on every PR, so the plugin keeps its own promises.

Optional Grok runtime

Claude Code is the installable plugin. This repo also ships a Grok workflow so a review can run as a background script. Marketplace install does not include it.

What it does

  • A config agent picks lenses. Those lenses run read-only.
  • One skeptic checks each finding. Missing evidence is not a yes.
  • Merge is read-only. The report is run scratch. Watch /workflows.
  • It does not apply product-code fixes. Interactive apply stays in /fit-review.

How to run it

  • Clone the repo. Open a Grok session in that directory.
  • Run /workflow fit-review {"target":"HEAD","base":"<merge-base commit SHA>"}. Get the SHA with git merge-base origin/main HEAD.
  • The script does not apply smell-first severity align or pattern policy, and it does not write docs/.
  • Details: .grok/workflows/README.md
Grok session, this repo 
# Grok session, this repo
/workflow fit-review {"target":"HEAD","base":"<merge-base commit SHA>"}

Published reports

Dogfood runs and workflow reviews from this repo. These are real outputs, not marketing copy.