An evidence-driven, platform-independent Agent Skill for reviewing substantial code modules and cross-file features.
Module Quality Reviewer maps a module before judging it, separates discovery from verification, and produces release-oriented findings backed by repository evidence. It is designed for developers, maintainers, architects, and reviewers who need more than a single-file code review or a generic checklist.
Large-module reviews often fail in predictable ways:
- They stop at the named file and miss callers, data flow, state transitions, recovery paths, and external boundaries.
- They apply the same checklist to every module instead of following the risks that matter to its business behavior.
- They present plausible inference as confirmed fact.
- They target a fixed issue count, encouraging weak findings, artificial splitting, or quota padding.
- They modify tests or create reproductions inside the target working tree, contaminating the system being reviewed.
- They collect broad first-pass observations but never re-test the highest-risk conclusions.
This project turns review into a two-pass evidence process: build an accurate module model, prioritize material risks, then deeply verify the findings that can change a release decision.
- Risk-led module mapping: traces entry points, callers, callees, data, state, trust, compatibility, and failure boundaries before reporting issues.
- Two review passes: separates broad discovery from focused high-risk verification and remediation design.
- Independent classification: every material item has a kind, severity, and confidence rather than one overloaded label.
- Evidence discipline: records inspected scope, commands, results, limitations, mitigations, and unresolved human decisions.
- Read-only safety: isolates reproductions and keeps changes to production code separate from review work.
- Repeatable quality controls: combines behavioral evaluation cases, regression tests, and a standard-library contract validator.
This repository is not a runtime service, model provider, linter, or replacement for domain experts. It requires no database, network service, model API credential, or third-party Python package. The quality of a review still depends on the Agent's repository access, execution permissions, context budget, and available business knowledge.
The recommended installation path is the open Agent Skills CLI. It discovers the repository's SKILL.md, installs the complete Skill into supported Agent directories, and can target either the current project or the user account. Node.js with npx is required for this installation method.
npx skills add junit/module-quality-reviewer --skill module-quality-reviewerInstallation is project-scoped by default; add -g for a global installation. The CLI prompts for the target Agent when needed, or you can use its --agent option for an explicit target. Start a new Agent session after installation so the Skill is discovered.
For development or pre-publication use, install directly from the current directory and validate the checkout:
git clone https://github.com/junit/module-quality-reviewer.git
cd module-quality-reviewer
npx skills add . --skill module-quality-reviewer
python3 scripts/validate_skill.py .The project validator uses only the Python standard library. The Skills CLI is the recommended distribution layer, while the installed Skill itself remains a text-based, platform-independent package.
After installation, ask your Agent to use module-quality-reviewer or make a request matching its description. The user only needs to identify a module path, feature name, or natural-language feature description.
First pass — discover and prioritize risks:
Review <module-path> for design, implementation, test quality, and release readiness. Keep the target repository read-only.
Second pass — verify a prior finding:
Verify finding F1 from <previous-report> against the current repository. Reject, narrow, confirm, or escalate it with evidence.
Both passes — explicitly request the complete workflow:
Run both review passes on <module-path>. Keep the target repository read-only and separate verified facts from remaining uncertainty.
The user only needs to identify the target. Business goals, constraints, known risks, and prior reports improve the review but are optional unless a second-pass conclusion depends on them.
If your Agent is not supported by the Skills CLI, preserve the complete repository structure and ask a file-aware Agent to read SKILL.md. If it cannot load local Skill files, use the complete prompts in references/portable-prompts.md.
| Mode | Select it when | Main output |
|---|---|---|
| First Pass — Discovery and Risk Finding | No prior report or finding set exists, including requests phrased as “comprehensive” or “deep” review | Module map, coverage ledger, evidence-backed findings, missing critical tests, and a prioritized second-pass queue |
| Second Pass — High-Risk Verification | The request supplies or references prior findings and asks to verify, re-test, or follow up | Status changes, strengthened evidence, retained findings, root causes, remediation plans, and a final release decision |
| Both Passes | The user explicitly requests both | A complete first pass followed by focused verification; first-pass hypotheses are not treated as confirmed until re-tested |
Mode selection is semantic: the word “deep” alone does not imply a second pass when no baseline exists.
- Locate and bound the module. Identify entry points, public contracts, callers, callees, persistence, configuration, tests, integrations, and relevant history.
- Build the runtime model. Describe the main call and data paths, invariants, state transitions, side effects, and failure or recovery behavior.
- Review by material risk. Prioritize incorrect business outcomes, data consistency, authorization, concurrency, recovery, compatibility, scalability, and blind spots in tests.
- Collect evidence. Run the smallest safe checks, search for mitigating guards, record exact results, and state what could not be verified.
- Classify and report. Keep finding kind, severity, and confidence independent; never invent findings to reach a count.
- Verify high-risk conclusions. In a second pass, confirm, reject, narrow, raise, or lower earlier findings and design implementable remediation for those that remain.
The shared report contract keeps conclusions comparable across both modes and ends with an explicit release-readiness decision.
flowchart TB
subgraph Usage["Usage layer"]
Request["Review request"]
Router["SKILL.md — routing and invariants"]
First["First-pass workflow — discovery and risk finding"]
Second["Second-pass workflow — high-risk verification"]
Portable["Portable prompts — manual-loading fallback"]
Report["Shared report contract — release decision"]
end
subgraph Quality["Quality-assurance layer"]
Metadata["Optional platform metadata"]
Evals["Behavior evaluation cases"]
Tests["Regression contract tests"]
Validator["Deterministic validator"]
end
Request --> Router
Router --> First
Router --> Second
Request --> Portable
Portable --> First
Portable --> Second
First --> Report
Second --> Report
Metadata -. adapter .-> Router
Evals --> Tests
Tests --> Validator
Validator -. validates .-> Router
Validator -. validates .-> Report
- SKILL.md is the entry point. It defines required input, selects the review mode, and holds the non-negotiable safety and classification rules.
- references/first-pass.md describes scope discovery, risk-bounded coverage, runtime modeling, basic verification, and construction of the second-pass queue.
- references/deep-review.md re-opens prioritized findings, searches for mitigating evidence, strengthens proof, identifies root causes, and designs remediation.
- references/report-format.md is the shared output contract for findings, verification records, human decisions, and release recommendations.
- references/portable-prompts.md preserves the workflow when an Agent cannot load Skills natively.
- agents/openai.yaml is optional platform metadata; it is an adapter, not a runtime dependency.
- evals/cases.json describes behavioral scenarios such as mode routing, no quota padding, isolated reproduction, and bounded coverage.
- scripts/validate_skill.py validates metadata, direct-child references, classification markers, evaluation structure, and unsafe contract regressions using the Python standard library.
- tests/test_validate_skill.py, tests/test_repository_contract.py, and tests/test_readme_contract.py protect the validator, runtime contract, and public documentation.
The runtime remains text-first and portable. The quality layer detects structural drift without adding a service or dependency to the review workflow.
Every material item is classified on three independent axes:
| Axis | Values | Question answered |
|---|---|---|
| Kind | Defect, Risk, Improvement, Decision |
What type of item is this? |
| Severity | Blocker, High, Medium, Low |
How serious is its impact? |
| Confidence | Confirmed, Highly likely, Needs confirmation |
How strong is the evidence? |
A high-value improvement is not automatically a defect. A severe impact does not make an uncertain hypothesis confirmed. A decision records a human choice or missing fact that changes the conclusion rather than disguising it as a code error.
Material findings include concrete evidence, the triggering condition, impact, relevant call path, why current safeguards miss the problem, remediation direction, and the next verification step.
Reviews are read-only by default:
- Do not modify production code, create commits, mutate production data or resources, send real external requests, or run destructive commands.
- Safe compilation, static checks, focused local tests, and read-only repository inspection are allowed when available.
- Put reproductions and temporary regression tests in an operating-system temporary directory or isolated copy outside the target working tree.
- Clean temporary artifacts and verify that the target working tree is unchanged.
- Never report an unexecuted check as passed; record the missing evidence and uncertainty instead.
- If isolation cannot faithfully represent the relevant integration boundary, leave the check unexecuted and explain the limitation.
- Change production code only after explicit user authorization, and keep remediation implementation separate from the review report.
These rules protect both the reviewed system and the credibility of the evidence.
module-quality-reviewer/
├── SKILL.md
├── agents/
│ └── openai.yaml
├── evals/
│ └── cases.json
├── references/
│ ├── deep-review.md
│ ├── first-pass.md
│ ├── portable-prompts.md
│ └── report-format.md
├── scripts/
│ └── validate_skill.py
├── tests/
│ ├── test_readme_contract.py
│ ├── test_repository_contract.py
│ └── test_validate_skill.py
├── LICENSE
├── README.md
└── README.zh-CN.md
Runtime instructions stay small and composable: the router contains shared invariants, each reference owns one workflow or output responsibility, and validation assets remain outside the Agent's review path.
Python 3 and its standard library are sufficient for the local release gate:
python3 -m unittest discover -s tests -v
python3 scripts/validate_skill.py .
python3 -m py_compile scripts/validate_skill.py tests/test_validate_skill.py tests/test_repository_contract.py tests/test_readme_contract.pyThe test suite verifies the validator's failure cases, the repository's runtime contract, and bilingual README parity. The contract validator checks the actual project directory and exits non-zero with actionable errors when an invariant is broken.
Use npx skills add as the primary installation path for supported Agents; it handles their different Skill directories without making this repository platform-specific. Install the published source with npx skills add junit/module-quality-reviewer --skill module-quality-reviewer, or install a local checkout with npx skills add . --skill module-quality-reviewer.
For an unsupported Agent, keep the directory intact so relative references resolve correctly. If it supports file context, load SKILL.md and the reference selected by its routing rules. If it cannot load local instruction files, copy the appropriate complete prompt from references/portable-prompts.md.
Whichever path you use, give the Agent access to the target repository and permission to run only the safe checks appropriate for that environment. State external constraints—such as unavailable services, limited context, or prohibited commands—so they appear as verification limitations rather than silent gaps.
Contributions should preserve the behavioral contract, not only improve wording.
- Keep shared invariants in SKILL.md and workflow-specific detail in the appropriate reference file.
- For behavior changes, first add a failing regression to tests/test_repository_contract.py or tests/test_validate_skill.py, or strengthen the relevant expectation in evals/cases.json.
- Update portable prompts and the report contract when a runtime rule affects manual-loading users or output structure.
- Run the complete validation commands above and confirm temporary checks did not alter the target repository.
- Update both README files together when public behavior, paths, or commands change; tests/test_readme_contract.py enforces their shared structure.
Keep additions evidence-focused, dependency-free, and proportional to material review risk. Avoid fixed issue quotas, platform lock-in, or instructions that claim checks succeeded without execution evidence.
Module Quality Reviewer is available under the MIT License.