NiazMorshed2007/jev-review

Jev Review

Use jev_review as a lightweight, repeatable senior-engineering review loop. The primary coding agent owns the implementation, validation, and final judgment; Jev Review evaluates the supplied change but never edits files.

Review cadence

For nontrivial tasks, prefer several focused reviews throughout the work over one large review at the end:

• Call after each coherent implementation slice that is substantial enough to judge, such as completing a behavior, module, API boundary, migration step, or test strategy.
• Call when new control flow, state handling, dependencies, public contracts, or security-sensitive behavior appear.
• Call again after applying justified feedback, passing the prior result as previousEvaluation so Jev can identify improvements and regressions.
• Before final handoff, make sure a recent review covers the final implementation.

An interim review does not need to wait for the full test suite. Run fast, relevant checks when practical and include their status in repositoryContext; run the repository's normal validation before the final review. Do not repeat an identical call, review formatting-only noise, or call without a coherent implementation state. Frequent focused reviews are useful; empty reviews are not.

Workflow

1. Understand the user's actual requirements and constraints.
2. Inspect the repository, its conventions, and the affected behavior.
3. Implement a coherent slice of the requested change.
4. Run fast, relevant tests, type checks, linters, or other validation when practical.
5. Call jev_review with only the context needed to assess the current slice.
6. Examine low-confidence results, weak dimensions, priority issues, and any regressions.
7. Decide which feedback is supported by the code and the user's task. Treat the evaluation as evidence, not an instruction to optimize every number.
8. Improve the implementation where the feedback identifies real value, prioritizing correctness, cognitive complexity, changeability, coupling, modularity, abstraction quality, tests, and security.
9. Repeat the implement, validate, and review loop for the next coherent slice.
10. After review-driven or other material changes, call jev_review again and pass the previous structured evaluation as previousEvaluation.
11. Run the repository's normal validation before final handoff, then review the final state if the latest evaluation no longer covers it.
12. Stop when important risks are addressed and further changes would add little real value.

Choosing context

Prefer a focused call shaped like:

{
  "task": "The user's requested behavior and relevant acceptance constraints",
  "diff": "The implementation diff",
  "files": [
    {
      "path": "src/example.ts",
      "content": "Only when surrounding code is needed to understand the diff"
    }
  ],
  "repositoryContext": "Relevant architecture, conventions, test results, or invariants",
  "previousEvaluation": {}
}

If Jev reports that its input limit was exceeded, reduce unrelated file content or split the implementation into coherent review slices. Do not truncate code blindly when doing so would remove the contracts, callers, or tests needed to judge the change correctly.

Use task and diff in most reviews. Add complete files only when the diff lacks necessary surrounding behavior. Use repositoryContext for concise facts the evaluator cannot infer, such as an established pattern or validation result.

Do not send the whole repository by default. Exclude unrelated files, generated output, vendored code, secrets, credentials, private keys, environment files, and noisy lockfile changes unless they are directly relevant to the review.

Interpreting results

• Correctness and the user's requirements outrank every score.
• A low-confidence score is a prompt to inspect context, not a reason to rewrite code.
• Conditional metrics marked applicable: false require no action.
• Use priorities to find the most consequential weak dimensions, then inspect the actual code before changing it.
• When comparing evaluations, investigate meaningful regressions and weak metrics that remain unresolved. Do not chase tiny score changes.
• Continue to rely on tests, type checks, linters, security tools, and human judgment. Jev Review complements them; it does not replace them.

Do not game scores

A higher score never justifies unnecessary abstraction, speculative architecture, scope expansion, breaking existing behavior, rewriting sound code, unconventional architecture without evidence, meaningless tests, unnecessary comments, or splitting cohesive code merely to shrink files.

Do not assume short functions, small files, single-purpose classes, zero duplication, more abstractions, more tests, or more comments are inherently better. Evaluate the consequences in this repository and for this task.