القائمة
Review code on the current branch for Qamomile philosophy and convention compliance. Compares changed files against `main` and evaluates them against Qamomile's design principles.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Create a summary markdown file for the current branch that explains its work relative to `origin/main`. This skill uses a separate subagent or AI model to validate the summary. Keep an eye on the usage limit.
Qamomile's mandatory cross-backend execution test policy for qamomile/circuit/algorithm/ and qamomile/circuit/stdlib/. Use whenever adding or modifying an algorithm/stdlib qkernel, or when adding a new SDK backend, so the change ships tests that actually transpile AND execute on every supported backend (Qiskit, QuriParts, CUDA-Q). Missing coverage is a P1 in /local-review.
Qamomile's mandatory Google-style docstring convention for every function, method, and class in qamomile/ (public and private alike). Use whenever writing or editing code under qamomile/ so the docstring has the required Args/Returns/Raises sections. Enforced by /local-review (missing docstrings are P2+).
docs/en/配下の英語ドキュメント(.py jupytext形式)をdocs/ja/に日本語翻訳する。翻訳ルールとワークフローを定義。
Generate Qamomile's EN/JA release notes (`docs/{en,ja}/release_notes/v<X_Y_Z>.md`) from the diff between the previous version tag and current main. Defines the section order, snippet verification, link conventions, and the related-file updates.
Simplifies and refines Python code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.
| name | local-review |
| description | Review code on the current branch for Qamomile philosophy and convention compliance. Compares changed files against `main` and evaluates them against Qamomile's design principles. |
| model | opus |
You are an expert code reviewer for the Qamomile quantum optimization SDK. Review the changes on the current branch against Qamomile's design philosophy and coding conventions.
Use these labels consistently when reporting findings (referenced by rules below and re-applied in Step 6):
except swallowing, float == in production code, missing exception chaining.@qkernel / backend-pattern violation; missing / stale / unexecuted .ipynb; new runnable docs not in test patterns; docs authoring-policy violation that can mislead readers or ship unverified claims; incomplete modifications (changed interface, callers not updated, __all__ stale); missing tolerance in numerical asserts; missing tests or docs for a new feature; OMMX parity break; missing cross-backend execution coverage for new algorithm/stdlib.range(...) in a qkernel body (use qmc.range(...) — qmc is the preferred qamomile.circuit alias; qm.range(...) works but is discouraged in new code).q = qm.h(q).qm.cx(q, q) is forbidden).qubits[i] = qm.h(qubits[i]) for single-qubit gates, qubits[i], qubits[j] = qm.cx(qubits[i], qubits[j]) (tuple assignment) for multi-qubit gates. These are always OK. If you take an element into a local name (q0 = qubits[0]), you must return it (qubits[0] = q0) before re-borrowing the same index into a local name or before using the array as a whole. Flag double-borrow of the same element into different locals, not the tuple-assignment form.Frontend (@qkernel) → IR → Transpiler Pipeline → Backend
Dependencies flow only downstream. The practical rules:
QKernel and DecompositionConfig as configuration inputs — e.g., SubstitutionPass takes QKernel as a substitution target and imports it under TYPE_CHECKING + runtime-late import (see qamomile/circuit/transpiler/passes/substitution.py:34,276). That pattern is NOT a layer violation. Flag only passes that reach into Frontend behavior or non-boundary internals.Qamomile prefers to keep the IR as abstract as possible and delegate concretization to the transpile target (backend emit / runtime). The IR encodes what the program means; how a backend realizes it (per-qubit instruction encoding, native composite-gate equivalents, runtime loop / branch lowering) is the backend's job. Concretizing too early at the IR layer locks Qamomile into a single backend's view and bypasses the emit-time extension surfaces — GateEmitter (per-gate emission), CompositeGateEmitter (native lowering of composite gates), and the emit pass itself when something needs structural customization.
Existing examples of the principle in code:
MeasureVectorOperation (qamomile/circuit/ir/operation/gate.py#L410) — not expanded into N per-qubit MeasureOperations at IR level. How it turns into actual measurement instructions is left to emit time: backends with a native vector primitive can emit one operation, others can iterate per-qubit. The IR does not commit to per-qubit semantics.MeasureQFixedOperation is HYBRID (quantum measurement + classical decode). It is split into MeasureVectorOperation + DecodeQFixedOperation only at plan's pre-segmentation lowering — late enough that the IR keeps the highest abstraction that still admits a clean classical/quantum segmentation boundary, and each resulting half remains as abstract as possible (no per-qubit expansion).CompositeGateOperation; native lowering is opt-in via CompositeGateEmitter.ForOperation; LoopAnalyzer decides unroll-vs-runtime-loop at emit time.Reviewer rules:
plan or emit) — is P1.GateEmitter, CompositeGateEmitter, or the emit pass itself can express the lowering — is P1 (also a Section B violation).MeasureQFixed → MeasureVector + DecodeQFixed is the canonical example). The check is whether each resulting half stays as abstract as possible.When ambiguous, prefer (a) a single abstract op over multiple low-level ones, and (b) lowering at the latest stage where the IR still cleanly expresses the abstraction.
@qm.qkernel (or @qmc.qkernel). CompositeGate._decompose() methods and emitter-side decomposition strategies are separate patterns (class method / strategy protocol) and are out of scope for this rule.qm.Qubit, qm.Float, qm.UInt, qm.Vector[...], qm.Dict[...]) — not Python primitives.qmc.range(...) (project convention — qmc is the preferred qamomile.circuit alias). The AST transformer technically also accepts plain range(...) and the legacy qm.range(...) alias, but the convention is to make quantum-side iteration explicit via qmc; older code using qm.range(...) is tolerated but new code should use qmc.range(...). Dict iteration can use either the native for k, v in mapping.items() form or the Qamomile form for k, v in qmc.items(mapping) — both are accepted (see qamomile/circuit/algorithm/fqaoa.py:115,118 for the qmc.items style). Plain Python iteration over arbitrary iterables (for x in some_list:) is not captured as an IR ForOperation — restrict that form to iteration over precomputed concrete data used via closures (e.g., numpy arrays referenced from within the kernel body).@qkernel building blocks; transpile() delegates rather than inlining circuit construction. If both a public getter (get_xxx_ansatz) and transpile() exist, transpile() must compose the getter.Applies to backend files under qamomile/{qiskit,quri_parts,cudaq,qbraid,...}/.
Transpiler[T], implement _create_segmentation_pass(), _create_emit_pass(), executor().QamomileCompileError and carry rich diagnostics (context, suggestions, available bindings). Use @dataclass for structured diagnostic payloads.raise NewError(...) from e when re-raising.except and no unconditional except Exception:. Catch specific types; graceful fallbacks must warnings.warn() the reason.__init__.py provides the curated public API via __all__ (no _-prefixed names in __all__ without justification). TYPE_CHECKING guards break circular imports.@dataclass for state-oriented types with field-wise equality; use a regular class when invariants, encapsulation, or custom equality matter.pyproject.toml's requires-python), X | None (not Optional[X]), extensive type annotations. enum.StrEnum is available from 3.11 and is the preferred pattern for closed-set parameters (see later in this section).Args / Returns / Raises as applicable and Example where helpful. Private helpers may use compact sections but must keep the structure. Tests (def test_...) are exempt from Args / Returns — a 1–2 line description of what is verified suffices; test helpers and fixtures follow the full rule. See CLAUDE.md's "Docstring Convention (MANDATORY)". Missing docstrings are P2+.Args: and Returns:. Args: entries MUST use the form name (type): description; Returns: MUST use the form type: description. Type annotations in the signature alone are NOT sufficient — Google-style requires the type to be repeated in the docstring as well so doc-generation tools (and human readers skimming the docstring without the signature) get a complete contract. Missing types in Args / Returns of a present docstring is P2 (separate from the "missing docstring entirely" P2+).enum.StrEnum and dispatched via the Enum internally. Signatures accept str | MyEnum and normalize at the entry (method = MyEnum(method); on failure raise ValueError listing the valid values). Internal dispatch via match (small sets, see Section L) or a ClassVar[dict[MyEnum, ...]] (8+ variants). Never construct a dict[str, callable] inside a hot-path method every call. Raw string == dispatch on closed sets is P2; per-call dict construction is P3.pytest with markers (docs, gate categories, backends); reuse base test suites (TranspilerTestSuite). Module-level @qkernel definitions are recommended for qkernels that are reused across tests or that rely on inspect.getsource at runtime; function-local @qkernel definitions (inside a test method) are acceptable for one-off test helpers.@pytest.mark.parametrize) and randomize (np.random.default_rng(seed) with fixed seeds) wherever inputs admit it.Args / Returns.0 / π / 2π) and negative tests (pytest.raises(ExpectedType)) are mandatory.np.allclose / np.testing.assert_allclose with explicit atol/rtol. Never element-wise == on floats.assert np.isclose(energy, -8.0) without justification is P2. Trivial cases (f(0) == 0) are exempt.(sample, energy, count) and the test checks only energy, regressions in the others go unnoticed. Missing asserts on deterministic outputs are P2. For parametrized cases with per-case deterministic properties, assert those per-case — do not collapse to the weakest shared assertion.@pytest.fixture.Any addition or non-trivial modification under qamomile/circuit/algorithm/ or qamomile/circuit/stdlib/ MUST ship with tests that transpile AND execute the new/changed qkernel on every supported backend — not just build the IR. Pure refactors that provably preserve IR output (same gate sequence, same shapes) are exempt — still advisable to re-run but not enforced.
Backend matrix:
| Backend | Transpiler | Executor |
|---|---|---|
| Qiskit | qamomile.qiskit.QiskitTranspiler | BasicSimulator / qiskit_aer.AerSimulator |
| QuriParts | qamomile.quri_parts.QuriPartsTranspiler | QuriParts state-vector sampler/estimator |
| CUDA-Q | qamomile.cudaq.CudaqTranspiler | cudaq state-vector simulator |
qBraid is out of scope (executor-only wrapper around Qiskit, requires API key). Optional coverage may gate on QBRAID_API_KEY.
Required per backend (parametrize or one test each):
transpiler.transpile(kernel, bindings=...) returns a real ExecutableProgram.executable.sample(executor, shots=...)) AND an expval path. The expval path goes through qmc.expval(q, hamiltonian) inside the kernel — executable.run(executor, ...) then returns an ExpvalJob — or, when working directly with the emitted circuit, the backend executor's estimate(circuit, hamiltonian) entry point. Sampler and estimator regress independently; exercising only one is insufficient.np.allclose for expval; statistical tolerance for sampling).pytest.importorskip("<sdk>").Randomize where the algorithm admits it: parametrize over seeds, register sizes (n ∈ {1, 2, 3, 5} — not a single n), and every degree of freedom (angles, phases, bitstrings, coefficients). Always seed via np.random.default_rng(seed). Include boundary inputs (0, π, 2π; single-qubit registers where applicable).
Large-problem escape hatch: when local simulation is genuinely infeasible (30+ qubits, dense Hamiltonians that blow up statevector memory), transpile() success + structural checks (gate / qubit count) suffice. Document the reason in the docstring. Prefer a small-scale parametrization that IS simulatable and reserve the escape hatch for the large scale.
Reverse direction: when a new backend SDK is added, extend every existing tests/circuit/algorithm/ and stdlib test (test_qft.py, test_qpe.py, ...) to cover it — refactoring the tests to be backend-parametrized if needed — with the same sample + expval + randomization requirements.
Severity: missing cross-backend execution is P1; fixed-inputs-only is P2; sampler-only or estimator-only when simulatable is P2; missing reverse-direction retro-extension in a new-backend PR is P1.
docs/, read docs/README.md before reviewing. Treat it as the source of truth for the docs build pipeline, authoring policy, skeleton usage, tag mechanism, and docs-test expectations. If this skill and docs/README.md disagree, prefer docs/README.md and flag this skill as stale.tutorial/, algorithm/, usage/, and integration/ must follow the reader-first, Qamomile-first, testable policy in docs/README.md's "Authoring Policy" section. Flag as P1 when a page ships unverified academic claims, misleading theory, or result claims without assertions/reference checks. Flag as P2 when a page drifts from one clear purpose, hides ordinary usage behind excessive theory, avoids Qamomile-native APIs/drawings where they are available, or lacks take-home summary points.docs/skeletons/ and preserve the required shape there: tag frontmatter, H1 scope paragraph, commented Colab install cell, imports cell, section-specific body, and ## Summary. Missing structure that makes the page hard to run or review is P1; smaller outline drift is P2. Do not require README to repeat the skeleton body outline..py is the authoring surface. Runnable article .py files must have a committed paired .ipynb that (a) exists, (b) stays in sync when its .py changes, and (c) contains execution outputs intended for readers. Any of these failing is P1. An .ipynb-only article change without a corresponding .py update is P2 because it bypasses the reviewable source.QAMOMILE_DOCS_TEST=1. If a PR updates notebook outputs that clearly came from test-mode shortcuts (reduced shots, reduced optimizer iterations, or placeholder results) without documenting that they are intentionally reader-facing, flag P1.docs/build.sh (especially show_help, SYNC_DIRS, TARGET_DIRS, setup_build_src, and command dispatch) and compare the changed prose against the implemented behavior. Flag nonexistent targets, removed Makefile guidance, stale command names, or claims that overstate what a target syncs/executes/builds.tutorial/, algorithm/, usage/, and integration/ must be discovered by TUTORIAL_PATTERNS in tests/docs/test_tutorials.py; missing coverage is P1. Do not exclude integration/ wholesale: skip only specific pages that require credentials or remote side effects via SKIP_TUTORIALS, and use OPTIONAL_SKIP_MODULES for optional package imports.docs/en/ and docs/ja/ must share file structure and content shape; only the natural language differs. Missing or outdated counterparts are P1. Non-rendered helper files such as docs/skeletons/ are exempt from en/ja pairing.index.md files are hand-written and should list the visible articles. New ordinary articles in existing sections should not require myst.yml edits because the TOC uses pattern: entries; unnecessary manual TOC edits are P2 if they risk stale navigation. New top-level sections still require the config updates described in docs/README.md.build_doc_tags.py injects chip blocks, browse-by-tag sections, and per-tag pages into _build_src/; committed docs/en/ and docs/ja/ sources should not contain those generated regions. Manually committed generated tag/chip content is P1 when it causes churn or stale rendered navigation, otherwise P2.ALLOWED_TAGS in docs/scripts/build_doc_tags.py): every tags: entry in an article's MyST frontmatter MUST already be in ALLOWED_TAGS. Adding a new tag to the whitelist as a side-effect of introducing an article is P1 unless the user explicitly requested the taxonomy change in the current task. If a new tag is genuinely needed, the PR should call it out explicitly and the ALLOWED_TAGS change should be a separate, documented decision.figure directives with explicit captions/alt text. Static images that are not generated by Python execution must be committed as files under the docs assets structure and referenced by path; do not embed them as notebook blobs/base64. Blobbed static images are P1 for large or reader-visible assets, otherwise P2.note blocks. Treat violations as P2 when they affect maintainability or reader clarity, otherwise P3.== / != on floats: use math.isclose(), np.isclose(), or the project's is_close_zero() utility. In tests, use np.allclose / np.testing.assert_allclose with explicit tolerances (Section H).def f(x: list[int] | None = None): x = x if x is not None else []..copy() in hot paths; prefer views or safe in-place ops.if-else and match MUST include an else / default branch. When no action is needed, leave an explicit comment or assert False, "unreachable".assert vs raise: assert for internal invariants (programmer error / specification unreachables). raise (with a QamomileCompileError-family type when in the compile pipeline) for conditions triggered by user input or external data.Applies to changes under qamomile/optimization/.
BinaryModel-touching changes: if a change introduces or modifies code that produces, consumes, or factory-constructs a BinaryModel (new constructors, new algorithms returning BinarySampleSet, new converters), verify the OMMX ingest/emit path is preserved or extended.
Instance ingestion parity. Silent divergence is P1.Solution / SampleSet, directly or via BinarySampleSet / decode_from_sampleresult). A terminal output with no OMMX representation is P1.if model.order > 2: raise ValueError(...)) or restricts itself to quadratic Ising, classify the restriction:
calc_energy, ΔE_k = -2·s_k·Σ_{inds∋k} coeff·Π s_i, etc.) generalizes in one line and the restriction is only there because a quadratic-specific helper was written. Propose lifting, or at minimum document that it is a convenience, not a mathematical limit. Unjustified incidental guards are P2.git diff main...HEAD --stat
git diff main...HEAD --name-status
git log main...HEAD --oneline
Before any human-style review, run the mechanical checks that GitHub CI enforces on every PR. (CLAUDE.md's "Build and Development Commands" documents the same tools at a narrower qamomile/-only scope; this skill follows CI's wider qamomile/ tests/ scope so the user sees what CI will see.) These are non-negotiable — execute them on every invocation of this skill and surface every failure in the final report. Never skip them, never "trust the diff looks clean", never stop after one check reports violations. Skipping these is itself a regression of the skill.
# Ruff lint + isort
# (CI: .github/workflows/ruff.yml — "Lint with ruff (Linter & isort)")
uv run ruff check qamomile/ tests/
# Ruff formatter check
# (CI: .github/workflows/ruff.yml — "Check formatting with ruff (Formatter)")
uv run ruff format --check qamomile/ tests/
# Type checking
# (CLAUDE.md "Build and Development Commands")
uv run zuban check qamomile/
Run all three even if earlier ones fail — each surfaces a different class of regression and the reviewer / user needs the full picture in one pass. Do not paraphrase the output; quote each failing line (file:line + message) verbatim in the report so the user can jump to it.
Severity mapping:
check violation — severity follows the underlying rule. A real bug rule (B006 mutable default, F841 unused assignment masking a typo, B008 mutable arg in function call) is P0. E722 (bare except) and B904 (missing from e on re-raise) are also P0 directly — the Severity Levels rubric at the top of this document lists "bare except swallowing" and "missing exception chaining" as P0 without conditioning on other sections, and the mechanical mapping must match. A pure style nit (E501 line length, I001 import order) is P3. A missing-docstring rule (D100–D107) is P2+ (CLAUDE.md "Docstring Convention (MANDATORY)").format divergence — P3. Mechanically fixable with uv run ruff format qamomile/ tests/; mention the one-liner in the recommendation.None-related foot-gun.Distinguish "the check ran and reported violations" (handled by the severity mapping above) from "the check could not be run at all". If a specific check tool fails to invoke — e.g., zuban is missing, a config file is broken, the formatter binary errors before reading any files — continue with the remaining checks and report the unrunnable tool as its own P0 finding. A non-runnable check is functionally equivalent to a disabled one and the user must be told, but stopping early would hide the other tools' output that may still be actionable. Only hard-stop the skill when uv itself is unavailable so that none of the three commands can run; in that case Step 1.5 as a whole is uninvokable and the skill cannot produce a valid review — report that single P0 and exit.
These checks scope to the whole qamomile/ + tests/ tree (matching CI), not just the diff. Pre-existing violations outside the diff still count, since the user will eventually be blocked by CI on them; report them too. The "pre-existing on main" annotation is optional and only valid when you actually verified it on main. If you want to label findings that way, run the same Step 1.5 commands against main in a temporary worktree and diff the outputs:
git worktree add /tmp/qamomile-base main
( cd /tmp/qamomile-base && uv run ruff check qamomile/ tests/; uv run ruff format --check qamomile/ tests/; uv run zuban check qamomile/ )
git worktree remove /tmp/qamomile-base
If you skip the baseline, report each violation without claiming whether it is pre-existing — an unverified annotation is more misleading than no annotation at all.
Read every new or modified file in full. Understand each file's role in the architecture.
Scale exploration to diff size:
Always: if a public symbol was added, removed, or renamed, verify __init__.py / __all__ were updated.
For each changed file, walk through Sections A–M and apply the ones relevant to that file. Each scoped section (D, H-bis, M) declares its scope in its opening lines; the remaining sections apply broadly.
After rules review, look for:
__all__ / __init__.py not updated; new behavior not covered by tests; .py / .ipynb / en / ja not kept in sync.None now raises); enum / constant additions that existing match / if-elif chains don't handle; pipeline pass ordering invalidated by a new pass.Mentally simulate applying all proposed fixes simultaneously and re-evaluate the finding set:
__all__ re-export). Add it.Severity of a consolidated finding inherits the highest severity among root cause and dependents. Three or more P3 findings under one architectural issue elevate to at least P2. If consolidation is still shifting after a second pass, stop and note it in the final report.
Common root-cause patterns to watch for: dead code (multiple nits on code never called — root cause is deletion); missing abstraction (repeated logic across findings — root cause is extract into a shared helper / qkernel); incomplete rename / refactor (mismatched names, broken references, stale imports); wrong layer (one misplaced import cascading into Section B violations); type / signature ripple (a type change not propagated to callers).
For each finding, give: severity (using the Severity Levels rubric at the top of this document), file:line, code snippet, the violated section, a short explanation, a concrete recommendation with corrected code, and — for consolidated findings — a Root cause of: line listing subsumed surface issues. End with a severity-grouped summary table.
Mechanical-check section (MANDATORY): the report MUST contain a top-of-report block titled ## Mechanical checks that lists the three Step 1.5 commands and, for each, one of:
passed (with the exit code and a one-line confirmation), orfailed (with the verbatim failing lines, and each failure also surfaced as a numbered finding below per the severity mapping in Step 1.5).Never omit this section, even when all three pass — a clean run is itself the evidence the user needs to satisfy CLAUDE.md's "Run /local-review before opening a PR" rule. If you do omit it, the skill output is not a valid local-review run.
If Step 5.5 did not stabilize, append: "Note: some findings may have deeper interdependencies warranting further investigation."