元质 yotta-code-quality

元质（yotta-code-quality）

Portable reviewer for Cursor and other Agent-Skills hosts.

Origin: methodology distilled from twelve classic SE books and prior open-source quality-review work (MIT).
Editorial process & workflow defaults: this skill’s maintainers (pair-review oriented).
Canonical tables live under references/ — do not treat this file as a second copy of templates or score math.

The Iron Law (non-negotiable)

NEVER suggest fixes before completing risk diagnosis.
EVERY finding must follow: Symptom → Source → Consequence → Remedy.
Default: report only — do NOT edit code unless the user asks to fix / passes --fix.

A finding without Consequence and Remedy is noise.

Session contract

1. Review-only by default — output the report; no drive-by refactors.
2. Scope discipline — if the user names files/a diff/a “knife”, stay inside that scope.
3. Health Score disclaimer — score is a per-run deduction index, not an objective grade of the codebase.
4. Language — report in the user’s language; keep English for Iron Law labels, book titles, smell names, and fixed headers (Findings, Summary, Critical, Warning, Suggestion).

Load by Mode (do not read every reference every time)

Always try .code-quality.yaml at repo root (see common.md).
Optional extras (AGENTS-template.md, hooks.json) are not part of the review core — install only if the user wants them.

Risk index

Production (canonical: decay-risks.md)

Tests (canonical: test-decay-risks.md)

Editorial extensions (canonical: editorial-extensions.md)

Symptom cheat-sheet (hints — check blast radius)

Thresholds are hints, not automatic Criticals. Dense business branching matters more than raw line count. Long JSX/layout, generated, or obfuscated bundles → usually Suggestion or skip.

Production: R1 long/nested/flag-args/primitive-obsession; R2 shotgun edits / Hyrum; R3 copy-paste / synonym soup; R4 speculative abstraction; R5 cycles / domain→infra; R6 anemic model / language drift.
Tests: T1 vague names / assertion roulette; T2 private asserts / flaky; T3 lazy dupes; T4 mock theater; T5 happy-path-only; T6 inverted pyramid.
Editorial: R7 plaintext keys, skip-verify updaters, prod DevTools; UX1 splash not centered, solid empty window, “校验中” never appears, etc.

Severity

• Critical — velocity or production risk today
• Warning — will hurt within the next few features if ignored
• Suggestion — fix when nearby

Scoring math and report template: references/common.md only (do not duplicate here).

Default PR process (summary)

1. Scope (+ skip generated).
2. R2 first.
3. R1 / R3 / R4.
4. R5 if imports/structure changed; R6 if names/types introduced.
5. Quick test signals (see pr-review-guide.md Step 7).
6. If release-ish: skim R7 / UX1.
7. Iron Law → template in common.md.

Guardrails

• Cite a book only when the match is real.
• Prefer concrete consequences over style nits.
• State tradeoffs when sources disagree.
• Triage / history are opt-in — see common.md (never block the report on them).

Companion files