Skip to content

Commit 5787a6f

Browse files
authored
docs: refine code-review skill with conformance, cache, and async checks (#989)
* docs: expose code-review skill under .github/skills for GitHub Copilot * docs: refine code-review skill with conformance, cache, and async checks
1 parent 1868810 commit 5787a6f

3 files changed

Lines changed: 15 additions & 12 deletions

File tree

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
name: review
2+
name: code-review
33
description: Conduct authoritative code review on python-roborock changes against repository architectural hierarchy, typing standards, and maintainer conventions.
44
---
55

@@ -13,11 +13,13 @@ All reviews are evaluated against the engineering conventions defined in [AGENTS
1313

1414
## Review Workflow
1515

16-
1. **Classify Changed Files by Layer**:
17-
Group changed files according to the 3-tier architectural hierarchy:
16+
1. **Classify Changed Files & Scope**:
17+
Group changed files according to the 3-tier architectural hierarchy and evaluate PR scoping:
1818
- **Priority 1: Public Trait APIs & Consumer Contracts** (`roborock/devices/traits/`, `roborock/data/containers.py`)
19-
- **Priority 2: Data Lifecycle & State Management** (trait state, callbacks, `RoborockDevice.close()`)
19+
- **Priority 2: Data Lifecycle & State Management** (trait state, callbacks, `RoborockDevice.close()`, map/render pipelines)
2020
- **Priority 3: Wire Protocols, Codecs & Cryptography** (`roborock/protocols/`, `roborock/devices/transport/`, `roborock/devices/rpc/`)
21+
- **PR Scoping**: Flag PRs that mix unrelated subsystems or combine large protocol/parser additions with trait consumption when they should be split into focused PRs.
22+
- **Automated Conformance**: Structural invariants (`RoborockBase` inheritance, `RoborockEnum` fallback members, `RoborockException` rooting, and trait boundary types) are enforced in `tests/conformance/`. Flag any unjustified allowlist exemptions added to `tests/conformance/` and focus deeper review energy on semantic, lifecycle, and design issues.
2123

2224
2. **Evaluate Layer 1: Public Trait APIs & Consumer Contracts**:
2325
- Are trait models subclassing `RoborockBase` with `@dataclass`?
@@ -28,9 +30,11 @@ All reviews are evaluated against the engineering conventions defined in [AGENTS
2830
- Are trait abstractions consumer-agnostic (not hardcoded exclusively to Home Assistant entities)?
2931
- Are transport details (keys, tokens, sockets) cleanly isolated from traits?
3032

31-
3. **Evaluate Layer 2: Lifecycle, State & Simplification**:
33+
3. **Evaluate Layer 2: Lifecycle, State & Concurrency**:
3234
- **Value-Returning Helpers**: Do helper functions return values instead of modifying `self` via hidden side effects?
3335
- **Direct Flow**: Is the execution path straightforward and direct, avoiding unnecessary indirection or ping-ponging between methods?
36+
- **Render & Cache Immutability**: Are cached telemetry state and raw packets kept immutable during presentation/rendering? When caching derived state (e.g., parsed maps or calibration), is cache invalidation handled accurately across out-of-order or concurrent updates?
37+
- **Event Loop Safety**: Are CPU-intensive operations (e.g., heavy map decompression or PIL image rendering) kept off the `asyncio` event loop (such as via `asyncio.to_thread`) with proper concurrency/staleness guards?
3438
- **Concurrency**: Does 1:1 async command-response matching use `asyncio.Future` correlated by protocol request/sequence ID (`request_id` or `msg_id`)?
3539
- **Teardown**: Are all tasks, event listeners, and channels cleanly unhooked in `RoborockDevice.close()`?
3640
- **Capability Gating**: Is capability gating checking protocol version, category (appropriate for device family), and device feature flags?
@@ -47,8 +51,6 @@ All reviews are evaluated against the engineering conventions defined in [AGENTS
4751
- Do assertions verify public behavior rather than private `_state` variables?
4852

4953
6. **Format Review Output**:
50-
Structure review comments with clear rationale and actionable code recommendations:
51-
- **Priority Level & File Reference**
52-
- **Issue / Anti-Pattern Identified**
53-
- **Grounded Rationale** (citing protocol resilience, consumer stability, or maintainability)
54-
- **Concrete Before / After Diff or Suggested Fix**
54+
Keep feedback high-signal: focus on architectural violations, state/concurrency bugs, protocol safety, and test gaps; avoid nitpicking formatting or style already enforced by Ruff and Mypy.
55+
- **Interactive / Summary Reviews**: Group findings by Priority Layer (1 → 3) with file references, the anti-pattern identified, grounded rationale (citing protocol resilience, consumer stability, or maintainability), and a concrete before/after diff or suggested fix.
56+
- **Inline PR Review Comments**: State the issue, grounded rationale (citing `AGENTS.md` conventions), and suggested fix concisely right on the affected lines.

‎.github/skills‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../.agents/skills

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,5 +97,5 @@ Evaluate every change against the repository's three core layers in strict prior
9797

9898
Portable agent skills following the [Agent Skills specification](https://agentskills.io/specification) are located under `.agents/skills/`:
9999

100-
- **Code Review Skill** (`.agents/skills/review/SKILL.md`):
101-
A structured, interactive review workflow for evaluating pull requests and diffs against the repository's architectural hierarchy, typing rules, and testing standards. To invoke during interactive sessions, refer to [.agents/skills/review/SKILL.md](.agents/skills/review/SKILL.md).
100+
- **Code Review Skill** (`.agents/skills/code-review/SKILL.md`):
101+
A structured, interactive review workflow for evaluating pull requests and diffs against the repository's architectural hierarchy, typing rules, and testing standards. To invoke during interactive sessions, refer to [.agents/skills/code-review/SKILL.md](.agents/skills/code-review/SKILL.md).

0 commit comments

Comments
 (0)