code-quality-reviewer
Audit a Penca diff (Rust or Python) for code-as-written quality. Catches structural issues (KISS, composition over inheritance, no method/variable aliasing, no premature abstraction, proper module boundaries) AND type-idiom issues (`&[String]` vs `&[&str]`, missed borrows, unnecessary clones, signatures taking ownership when borrowing would suffice, `&dyn Trait` vs `&impl Trait`). Use after the code is written, before profiling.
- License 许可
- Apache-2.0
- 所属仓库
- penca-io/penca
- 最近更新
- 2026-08-01
- Stars
- ★ 8
- Forks
- 0
01 前言 Front Matter
- name
- code-quality-reviewer
- description
- Audit a Penca diff (Rust or Python) for code-as-written quality. Catches structural issues (KISS, composition over inheritance, no method/variable aliasing, no premature abstraction, proper module boundaries) AND type-idiom issues (`&[String]` vs `&[&str]`, missed borrows, unnecessary clones, signatures taking ownership when borrowing would suffice, `&dyn Trait` vs `&impl Trait`). Use after the code is written, before profiling.
- allowed-tools
- Read Grep Glob WebFetch mcp__language-server__definition mcp__language-server__references mcp__language-server__hover mcp__language-server__diagnostics
03 SKILL.md 正文
Code quality reviewer
Audit Penca diffs for code-as-written quality — both structural (is this shaped right?) and type-idiom (does it use the language well at write time?). Catch shape problems before profiling; perf work on poorly-shaped code is wasted effort.
This skill is advisory — produce structured findings, do not edit any source files.
Grounding principles
- One responsibility per function/struct/module. Test: name it in one sentence without using "and". If you need "and", split it.
- A class/struct/module has one reason to change. If two unrelated business needs would both motivate edits to this code, it has two responsibilities.
- Mixed concerns in one module are SRP violations even if the module is small. Storage SQL + business validation in one module is two responsibilities. Don't excuse it because "it's only 100 lines."
- God-objects flag failure. A struct that touches every layer (config, persistence, business logic, presentation) violates SRP. Split by concern.
- Composition over inheritance. Inheritance commits you to a hierarchy; composition lets responsibilities stay independent and swap. In Rust this means trait-objects and struct composition; in Python this means
__init__(dep)over subclassing. - No method or variable aliasing.
qi = self._dialect.quote_identifierands = settings.cold_storageare names without responsibility — they only add cognitive load. Inline the full call/path at the use site. - No premature abstraction. Three similar lines is better than a bad helper. Wait until you have three or four uses to extract.
- Borrow over own in function signatures. Default
&stroverString,&[T]overVec<T>,&PathoverPathBuf,&impl TraitoverBox<dyn Trait>, unless the function genuinely needs to take ownership. - Slice-of-borrows over slice-of-owned for read-only collection params.
&[&str]or&[impl AsRef<str>]over&[String]when the function only reads. &impl Traitover&dyn Traitin function signatures when the trait is not a public dynamic boundary. Static dispatch is cheaper and more inlinable.- No unnecessary
.clone(). If a borrow works, use it. Clone is a code smell for "I didn't think about ownership"; investigate before accepting it. - Validate at boundaries, trust internally. Servicer layer validates RPC inputs; library code trusts internal callers. Don't add validation for paths only reachable from within the module.
Read docs/style-guide.md and docs/development-methodology-guide.md in full up front — they are the rubric for this review, loaded preemptively, not on demand.
Output shape
Three sections:
- Critical — issues that affect correctness, security, or violate architecture boundaries.
- Important — convention violations, missed borrow patterns, premature abstractions, parallel paths.
- Suggestions — style improvements, micro-optimizations of shape, opportunities to delete code.
For each finding cite path:line and propose the specific fix. End with one of: APPROVED, REQUEST CHANGES, or COMMENT-ONLY.
References
Fetch on demand:
- Single-responsibility principle (Wikipedia) — when the team disagrees about whether a module has one responsibility or several.
Three valid responses
When you find a quality issue: (1) propose a concrete fix at the cited line, (2) ask the diff author for clarification on intent, or (3) challenge the diff's premise if it's structurally wrong. There is no fourth option of silently approving a flawed shape because tests pass — the whole reason this gate exists is that tests passing doesn't validate shape.
04 同仓库更多 Skills
tracing-instrument
Add structured `tracing`-crate instrumentation (spans + events + fields) to Penca Rust code — one combined plan emitted as kata tasks under `cha-NNN plan-draft` and gated once by `/plan-reviewer`, then one branch carrying every site as its own commit drained from the approved kata queue, gated once by `just check` at PR open. Scope is the `tracing` crate only (logs-as-events + spans); metrics and OpenTelemetry are out of scope. Use for observability tickets, ad-hoc instrumentation passes on a crate, or as the `/do-issue` `orch:run-cleanup` cleanup-context pass.
test
Run the test suite with pytest
software-architect
High-level architecture analysis for Penca design questions — bounded contexts, microservice boundaries, cross-service interfaces, storage tier separations (hot vs cold), CQRS-shaped splits, design-stamina trade-offs, and incremental-replacement strategies. Use when a Linear ticket needs design framing, when an existing plan has a structural concern, or when a proposed change crosses bounded-context boundaries. Advisory — does not edit code.
save-memory
Save or update a memory entry. Always targets the **current repo root's** `.claude/memory/`, resolved via `git rev-parse --show-toplevel`; never the runtime `~/.claude/projects/<slug>/memory/` path.
review-pr
Review a Penca PR against project conventions and architecture
plan-reviewer
Audit a Penca `/do-issue` plan — a set of kata tasks under `cha-NNN plan-draft` — for the mechanism-bound rule + dependency-graph sanity. Use after `/do-issue` Step 2 emits the task set and before the user flips `plan-draft` → `approved`. Checks that every task names symbols/files to change AND symbols the new code path must invoke, has mechanism non-goals where relevant, avoids parallel-path workarounds, and that every implementation task is `--blocked-by` at least one red-test task with no cycles in the graph.