dsh-code-review

name	dsh-code-review
description	Use when reviewing a pull request in the deepseek-harness repo — orients the reviewer to this codebase's standards (AGENTS.md conventions, defensive patterns, ADRs, quality gates) and the review-specific checks that code alone can't show

Reviewing a DeepSeek-Harness PR

This skill is guidance, not a complete checklist. Verify and fetch the PR's live base and exact head, then run pnpm --silent run change-scope --base <verified-base-ref> --head <verified-head-ref> before reading the diff and enough surrounding code to understand the design. The report identifies paths and dirty layers but does not replace semantic review. Re-establish the base and rerun it after a retarget or merge. Prioritize correctness, lifecycle, security, and contract failures over style; a short review with one substantiated blocker is better than a list of nits.

Sources of truth

• AGENTS.md and packages/AGENTS.md: standing repository and package authoring contracts.
• docs/defensive-patterns.md: subprocess, callback, async-state, and disposal bug classes.
• docs/AGENTS.md: documentation placement and prose discipline.
• dsh-prose-standard: required coverage and editorial judgment for comments, docs, prompts, and visible strings.
• docs/testing.md and the quality-gates Agent Note: required test tiers and gates.
• Agent Notes: design rationale. Treat disagreement with an Agent Note as a design discussion, not an automatic veto.
• For bilingual changes, read translation-rules.md, terminology.md, and dsh-translate-docs.

Blocking requirements

1. New prose receives semantic review. Use dsh-prose-standard to critically review every added or changed Markdown passage, JSDoc, comment, prompt, description, diagnostic, and visible string. Verify required coverage, accuracy, placement, and editorial quality against the owning code or behavior; automated checks do not establish those properties.
2. Docs match the code. Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home.
3. Core type docs match. Changes to spine or seam vocabulary update the appropriate subsystems page and any type-equiv entry. Internal types need no catalog entry.
4. Registrations clean up. Verify each new registry contribution satisfies the disposal-test contract in packages/AGENTS.md.
5. Invariant companions are semantic. For every touched ./invariant, require an owner event-stream or mutable-data relationship at its authoritative boundary; service or method presence, plugin metadata or effects, and fixed pure examples belong in type, load, or unit tests. Accept an empty installer when its package-specific reason establishes that no plausible runtime relationship exists; do not demand an invented check merely to eliminate emptiness (repository rule; package contract).
6. Required evidence exists. Verify the author ran the relevant local checks for the diff and that CI covers the exhaustive matrix; review the semantic gaps neither can detect.

Manual checks

• Intent and seam contracts: trace both sides of every changed interface. Confirm the implementation matches the PR and any Agent Note, including errors, cancellation, ownership, and disposal.
• Lifecycle and concurrency: for async setup, callbacks, processes, or teardown, apply defensive-patterns.md. Check races before publication, cancellation during awaits, independent error reporting, callback containment, ownership before reentry, complete detach cleanup, and quiescent disposal.
• Capability and consumer fit: trace every current consumer, then flag consumer-specific behavior leaking into the interface under the package contract. Flag the inverse too: a new public method on a generic service (registry, session, agent) whose only caller is one internal consumer is an ad-hoc surface widening — require a private capability closure handed to that consumer at construction instead.
• Scope, ownership, and necessity: map each abstraction, state machine, option, defensive copy, and compatibility path to its current contract, production consumer, and owning plugin or service. Challenge unrelated features and speculative generality, then test the PR's coherence against the root contract.
• Configuration and public choices: ask what current-consumer evidence or prior art supports each default, public operation set, format, or imported external concept. Require an explicit choice or deferral when that evidence is absent.
• Model perspective: inspect the exact prompts, tool schemas, results, and diagnostics the model receives across affected modes. Flag concepts outside the model's task, then verify stable text verbatim and dynamic behavior through snapshots or end-to-end coverage.
• Enforcement boundaries: follow every denial path to the operation that executes it; exercise direct and alternate callers that can bypass schemas, prompts, facades, wrappers, or listener ordering.
• Borrowed and derived state: classify each retained value under the package boundary contract, then trace notifications and every cache, prompt, UI echo, replay, and query view to the documented success point and authoritative source.
• Bounds cover the final operation: locate the owner of the complete emitted or retained result, including wrappers and metadata. Probe tiny and exact limits, oversized single chunks, and multibyte text for byte limits.
• Real entry path: tests exercise the shipped Loader, bin, worker, ACP bridge, or subprocess where relevant. A hand-mounted plugin does not catch Loader export-shape failures; a function plugin must named-export its namespace and have no default export.

Reporting findings

State the defect, location, impact, and evidence. Place a localized defect inline on the tightest relevant diff range; use a PR-level comment for cross-cutting architecture, scope, or review-wide synthesis. Separate blockers from suggestions and omit issues already enforced by a green gate. Use the existing GitHub review thread for replies. When receiving review, verify each claim and fix or rebut it on technical grounds without performative agreement.