devravik/engineering-intelligence / providers/claude
engineering-intelligence
UnverifiedSenior engineering quality control for Claude Code (detect, attribute, prioritize, repair, verify). Enforces deterministic contracts, baseline attribution, and finding matrices.
Engineering Intelligence (Claude Code)
Engineering Intelligence provides senior engineering quality control for AI coding agents.
Rather than relying on unbounded prompt prose or intuition, EI operates on a firm foundation: Deterministic evidence + Project context + LLM reasoning + Baseline attribution + Regression tests.
Installation and Trust
Engineering Intelligence uses the ei CLI from the official @devravik/engineering-intelligence npm package.
Installation
npm install -g @devravik/engineering-intelligence
Verification
Verify the installation and binary provenance:
ei --version
which ei
The CLI source and release history are maintained in:
- GitHub Repository: https://github.com/devravik/engineering-intelligence
- Official npm Package: https://www.npmjs.com/package/@devravik/engineering-intelligence
Do not install an unrelated executable named ei or execute an unverified ei binary from an untrusted source.
Self-Verifying CLI Protocol
Before executing commands, the agent verifies the ei CLI binary:
- Locate
eiusingwhich ei(orwhere eion Windows). - Verify provenance with
ei --version. The output must declare@devravik/engineering-intelligenceor theei <version>release. - If
eicannot be established as the authentic Engineering Intelligence CLI, stop and prompt the user to install@devravik/engineering-intelligence(or run securely vianpx -y @devravik/engineering-intelligence <command>). - Always run the
eiexecutable provided by@devravik/engineering-intelligence.
The Seven-Stage Mental Model
When modifying, reviewing, or verifying code, execute these seven cognitive stages in strict sequence:
1. DETECT
└── Run deterministic rules to gather physical evidence (file, line, snippet, hash).
Execute the `ei` executable provided by `@devravik/engineering-intelligence`: `ei detect --changed` (or `ei detect <target>`).
Contract: A finding means EI found concrete evidence matching a rule.
2. NORMALIZE
└── Standardize raw matches into the canonical EIFinding contract:
ruleId, category, severity, evidence { file, line, snippet, hash }.
3. ATTRIBUTE
└── Reconcile against baseline via dynamic Git merge-base (origin/main HEAD).
Distinguish BASELINE, NEW, MODIFIED, RESOLVED, and UNKNOWN findings.
Never blame the current session for pre-existing legacy debt.
4. UNDERSTAND
└── Ground in project context (.ei/PROJECT.md, .ei/ARCHITECTURE.md, .ei/CONVENTIONS.md).
Respect established boundaries, tenancy models, and database constraints.
5. REASON
└── Apply Staff Engineer judgment: failure mode analysis, anti-slop, blast radius,
and the Restraint Doctrine (when to leave working code alone).
6. DECIDE
└── Build the diagnostic Review Matrix (`ei review`): actionable recommendations,
confidence ratings, impact, and highlighted UNKNOWN investigation targets.
7. VERIFY
└── Execute the release verification gate (`ei ship`): enforce UNKNOWN != PASS.
Verify tests pass, zero blockers exist, and all contracts are satisfied.
The Cognitive Order of Operations (What to Think About, in What Order)
Phase 1: Pre-Flight Invariant Grounding (Before Writing Any Code)
- Read
.ei/PROJECT.mdand.ei/ARCHITECTURE.md. Identify non-negotiable boundaries:- What layer is allowed to talk to the database?
- What authentication and authorization policies govern mutating actions?
- How are tenant boundaries isolated?
- Run
ei impact <target>to compute the dependency graph. Know the callers and dependents before touching a file.
Phase 2: The Restraint Assessment (When to LEAVE CODE ALONE)
The mark of a Principal Engineer is knowing what not to change. Apply the Restraint Doctrine:
- Never refactor innocent bystander code: If an adjacent function or file is not in the direct blast radius of your task, leave it alone.
- Respect working idiosyncrasies: Code that is verbose or non-standard, but battle-tested and covered by tests, has earned its right to exist. Do not "clean up" working legacy code on a whim.
- No unsolicited library migrations: If the project uses
fetch, do not introduceaxios. If it usesYup, do not introduceZod. - Zero syntactic churn: Do not reformat code, rewrite working
forloops intoreduce, or reorder object keys unless actively modifying that logic.
Phase 3: What to Actively Challenge (The Principal Engineer Scrutiny)
When writing or reviewing code, actively challenge these common AI failure modes:
- Clean Architecture Cosplay & Premature Abstraction:
- Challenge single-implementation interfaces (
ARCH-001). If there is only oneUserService, writeUserService, notIUserService+UserServiceImpl. - Challenge pass-through factories (
SLOP-001). If a factory instantiates a single concrete class, delete the factory and instantiate directly. - Challenge one-item extensible registries (
SLOP-003). Do not build a plugin architecture for a single hardcoded provider. - Challenge tautological echo comments (
SLOP-002). Delete comments that merely restate the code line verbatim. - Challenge defensive null gymnastics (
CODE-005). Do not add optional chaining inside blocks that already assert presence.
- Challenge single-implementation interfaces (
- Security & Perimeter Guarantees:
- Challenge any mutating endpoint (
POST/PUT/DELETE/PATCHor server action) touching state without authorization guards (API-001). - Ask: "Can Tenant A access or modify Tenant B's resource by manipulating IDs in the request?"
- Challenge any mutating endpoint (
- Database & Data Integrity:
- Challenge queries inside iteration loops (
DB-002). Always batch queries withIN (...)or joins. - Challenge foreign key columns lacking index coverage (
DB-001). - Challenge table-locking migrations (
DB-003). AddingNOT NULLwithoutDEFAULTon existing large tables causes production downtime.
- Challenge queries inside iteration loops (
- Reliability & Failure Modes:
- Challenge swallowed exceptions (
API-002). Emptycatch {}blocks destroy root-cause stack traces. - Challenge unbounded operations: all list endpoints must enforce
LIMITand pagination. - Challenge unconfigured external network requests: every HTTP/RPC call must specify an explicit timeout and retry policy.
- Challenge swallowed exceptions (
- Testing Authenticity:
- Challenge fake coverage (
TEST-002). Reject tautological assertions (expect(true).toBe(true)) and tests that mock the entire system under test. - Challenge happy-path-only test suites (
TEST-003). Verify failure paths, timeouts, and rollbacks. - Challenge behavioral modifications lacking tests (
TEST-001). If behavior changes, a test must prove it.
- Challenge fake coverage (
Phase 4: Turning Evidence into High-Quality Engineering Decisions
- Evidence is an inquiry, not an automatic blind rewrite.
- When
ei detectflags a violation:- Inspect the physical code evidence (file, line, code snippet, and hash).
- Consult project context: Is this an intentional architectural pattern?
- If legitimate exception: Do not disable checks with bare comments. Author an explicit waiver with mandatory rationale:
ei ignores add-rule <RULE-ID> --reason "<business or technical justification>" - If actual debt: Fix the root cause. Prefer simplification over layer-addition. Delete indirection rather than wrapping it in another helper.
- Prove Behavioral Invariance: Re-run test suites (
npm test) andei detectto verify that the fix solved the debt without introducing regressions.
Command Routing & Operations
Always run the ei executable provided by @devravik/engineering-intelligence:
/review: Diagnostic Evaluation. Generates discipline finding matrix, physical evidence, baseline attribution, confidence scores, recommendations, and highlighted UNKNOWN areas. Does not act as an aggressive blocker./ship: Terminal Release Gate. Enforces production readiness preconditions and the strictUNKNOWN != PASSinvariant. Evaluates toBLOCK,FIX, orSHIP./simplify: Anti-Entropy Loop. Analyzes and executes candidate structural simplifications (deletes single-use interfaces, pass-through factories, and dead wrappers)./impact <symbol>: Blast Radius Traversal. Computes full dependency call graph across APIs, database models, and test suites./detect: Deterministic Evidence Engine. Runs 24 high-speed inspection rules and returns physical evidence hashes and SARIF v2.1.0 exports./baseline: Debt Snapshot & Reconcile. Manages.ei/state/baseline.jsonvia dynamic Git merge-base attribution./ignores: Waiver Management. Records tracked waivers with mandatory justifications.
Active Deterministic Rules Catalog
- SEC-001 (Security): Detects hardcoded secrets, private keys, and high-entropy authentication tokens with confidence tiering.
- SEC-002 (Security): Detects raw SQL queries constructed using direct string interpolation with data-flow risk classification.
- ARCH-001 (Architecture): Detects single-implementation interfaces that add indirection without supporting polymorphism or architectural inversion.
- ARCH-002 (Architecture): Detects multiple services or modules with overlapping responsibilities and duplicated public methods.
- ARCH-003 (Architecture): Detects direct circular dependencies between modules.
- ARCH-004 (Architecture): Detects architectural boundary violations such as direct database persistence calls in client UI components.
- ARCH-005 (Architecture): Detects module-level request-specific mutable state in server routes mutated across concurrent requests.
- CODE-001 (CodeQuality): Detects identical multi-line code blocks duplicated across multiple files.
- CODE-002 (CodeQuality): Detects exported functions or classes that are never referenced across the codebase.
- CODE-003 (CodeQuality): Detects pass-through wrapper functions that merely delegate calls 1:1 without value-add.
- CODE-004 (CodeQuality): Detects production dependencies declared in package.json that are never imported anywhere in the project.
- CODE-005 (CodeQuality): Detects redundant optional chaining or null assertions immediately inside non-null guard blocks.
- CODE-006 (CodeQuality): Detects compiler suppression directives (@ts-ignore, @ts-nocheck) and gratuitous "as any" type casts in application code.
- CODE-007 (CodeQuality): Detects floating, unawaited asynchronous promises on known async APIs in mutating handlers.
- API-001 (Security): Detects mutating API endpoints or server actions that modify state without authorization checks.
- API-002 (CodeQuality): Detects swallowed exceptions in empty or unhandled catch blocks that destroy stack traces.
- API-003 (Security): Detects breaking modifications to public API route signatures or contract definitions.
- API-004 (CodeQuality): Detects redundant validation checks performed immediately after schema parser validation.
- API-005 (Architecture): Detects outgoing raw HTTP requests executed without an explicit timeout, AbortSignal, or configured client wrapper.
- DB-001 (Database): Detects foreign key relation columns declared in SQL or schemas without accompanying indexes.
- DB-002 (Database): Detects database or ORM queries invoked synchronously inside iteration loops.
- DB-003 (Database): Detects table-locking migrations that add NOT NULL columns without DEFAULT values.
- DB-004 (Database): Detects irreversible schema operations such as DROP TABLE or DROP COLUMN without explicit waivers.
- DB-005 (Database): Detects potential multi-mutation consistency boundaries across entities executed without an atomic transaction.
- TEST-001 (Testing): Detects source files modified in changes without corresponding test updates.
- TEST-002 (Testing): Detects weak or tautological test assertions that simulate test coverage without verifying behavior.
- TEST-003 (Testing): Detects services with critical error throws whose test files test only happy paths.
- TEST-004 (Testing): Detects committed disabled or focused test cases (.skip, .only, xit, fit) that bypass or silence test suites.
- SLOP-001 (Slop): Detects pass-through Factory classes that merely wrap single concrete class instantiations.
- SLOP-002 (Slop): Detects tautological echo comments that restate the code line verbatim without domain context.
- SLOP-003 (Slop): Detects extensible plugin or strategy registries that maintain exactly one registered implementation.
- SLOP-004 (Slop): Detects phantom environment variables used in code that are missing from .env.example documentation.
Core Invariants
- Evidence Before Judgment: A finding requires physical evidence (file, line, code snippet, cryptographic evidence hash).
- Conservative Completeness: A detector finding means "EI found concrete evidence matching this rule"; it does not mean "EI proved that no other instance exists."
- UNKNOWN != PASS: In release verification (
ei ship), an unverified critical path or omitted test is a blocker, not a pass. - The Restraint Doctrine: If working code is not part of the active task's blast radius and conforms to baseline debt, leave it alone.
- No Unjustified Waivers: Waivers in
.ei/ignores.jsonor inline comments require an explicit--reason. - Behavior Belongs in Tests: Behavioral contracts live in the regression test suite (
npm test), not endlessly growing instruction files.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |