mandrel 2.0.0 → 2.2.0

package/.agents/skills/core/code-review-and-quality/reference.md

@@ -0,0 +1,458 @@
+# Code Review and Quality — Reference (on-demand)
+
+**Read this when** a task engages one of the sections below and the Policy
+Capsule in [`SKILL.md`](SKILL.md) does not settle it on its own. The capsule
+is the contract; this file is the reference material behind it. Nothing here
+relaxes a capsule MUST, and nothing here is required reading merely because
+the skill is active.
+
+## Overview
+
+Multi-dimensional code review with quality gates. Every change gets reviewed
+before merge — no exceptions. Review covers five axes: correctness, readability,
+architecture, security, and performance.
+
+**The approval standard:** Approve a change when it definitely improves overall
+code health, even if it isn't perfect. Perfect code doesn't exist — the goal is
+continuous improvement. Don't block a change because it isn't exactly how you
+would have written it. If it improves the codebase and follows the project's
+conventions, approve it.
+
+## When to Use
+
+- Before merging any PR or change
+- After completing a feature implementation
+- When another agent or model produced code you need to evaluate
+- When refactoring existing code
+- After any bug fix (review both the fix and the regression test)
+
+## The Five-Axis Review
+
+Every review evaluates code across these dimensions:
+
+### 1. Correctness
+
+Does the code do what it claims to do?
+
+- Does it match the spec or task requirements?
+- Are edge cases handled (null, empty, boundary values)?
+- Are error paths handled (not just the happy path)?
+- Does it pass all tests? Are the tests actually testing the right things?
+- Are there off-by-one errors, race conditions, or state inconsistencies?
+
+### 2. Readability & Simplicity
+
+Can another engineer (or agent) understand this code without the author
+explaining it?
+
+- Are names descriptive and consistent with project conventions? (No `temp`,
+  `data`, `result` without context)
+- Is the control flow straightforward (avoid nested ternaries, deep callbacks)?
+- Is the code organized logically (related code grouped, clear module
+  boundaries)?
+- Are there any "clever" tricks that should be simplified?
+- **Could this be done in fewer lines?** (1000 lines where 100 suffice is a
+  failure)
+- **Are abstractions earning their complexity?** (Don't generalize until the
+  third use case)
+- Would comments help clarify non-obvious intent? (But don't comment obvious
+  code.)
+- Are there dead code artifacts: no-op variables (`_unused`), backwards-compat
+  shims, or `// removed` comments?
+
+### 3. Architecture
+
+Does the change fit the system's design?
+
+- Does it follow existing patterns or introduce a new one? If new, is it
+  justified?
+- Does it maintain clean module boundaries?
+- Is there code duplication that should be shared?
+- Are dependencies flowing in the right direction (no circular dependencies)?
+- Is the abstraction level appropriate (not over-engineered, not too coupled)?
+
+### 4. Security
+
+For detailed security guidance, see `security-and-hardening`. Does the change
+introduce vulnerabilities?
+
+- Is user input validated and sanitized?
+- Are secrets kept out of code, logs, and version control?
+- Is authentication/authorization checked where needed?
+- Are SQL queries parameterized (no string concatenation)?
+- Are outputs encoded to prevent XSS?
+- Are dependencies from trusted sources with no known vulnerabilities?
+- Is data from external sources (APIs, logs, user content, config files) treated
+  as untrusted?
+- Are external data flows validated at system boundaries before use in logic or
+  rendering?
+
+### 5. Performance
+
+Measure before optimizing, and only on the hot path. Does the change introduce
+performance problems?
+
+- Any N+1 query patterns?
+- Any unbounded loops or unconstrained data fetching?
+- Any synchronous operations that should be async?
+- Any unnecessary re-renders in UI components?
+- Any missing pagination on list endpoints?
+- Any large objects created in hot paths?
+
+## Change Sizing
+
+Small, focused changes are easier to review, faster to merge, and safer to
+deploy. Target these sizes:
+
+```text
+~100 lines changed   → Good. Reviewable in one sitting.
+~300 lines changed   → Acceptable if it's a single logical change.
+~1000 lines changed  → Too large. Split it.
+```
+
+**What counts as "one change":** A single self-contained modification that
+addresses one thing, includes related tests, and keeps the system functional
+after submission. One part of a feature — not the whole feature.
+
+**Splitting strategies when a change is too large:**
+
+| Strategy          | How                                                     | When                    |
+| ----------------- | ------------------------------------------------------- | ----------------------- |
+| **Stack**         | Submit a small change, start the next one based on it   | Sequential dependencies |
+| **By file group** | Separate changes for groups needing different reviewers | Cross-cutting concerns  |
+| **Horizontal**    | Create shared code/stubs first, then consumers          | Layered architecture    |
+| **Vertical**      | Break into smaller full-stack slices of the feature     | Feature work            |
+
+**When large changes are acceptable:** Complete file deletions and automated
+refactoring where the reviewer only needs to verify intent, not every line.
+
+**Separate refactoring from feature work.** A change that refactors existing
+code and adds new behavior is two changes — submit them separately. Small
+cleanups (variable renaming) can be included at reviewer discretion.
+
+## Change Descriptions
+
+Every change needs a description that stands alone in version control history.
+
+**First line:** Short, imperative, standalone. "Delete the FizzBuzz RPC" not
+"Deleting the FizzBuzz RPC." Must be informative enough that someone searching
+history can understand the change without reading the diff.
+
+**Body:** What is changing and why. Include context, decisions, and reasoning
+not visible in the code itself. Link to bug numbers, benchmark results, or
+design docs where relevant. Acknowledge approach shortcomings when they exist.
+
+**Anti-patterns:** "Fix bug," "Fix build," "Add patch," "Moving code from A to
+B," "Phase 1," "Add convenience functions."
+
+## Review Process
+
+### Step 1: Understand the Context
+
+Before looking at code, understand the intent:
+
+```text
+- What is this change trying to accomplish?
+- What spec or task does it implement?
+- What is the expected behavior change?
+```
+
+### Step 2: Review the Tests First
+
+Tests reveal intent and coverage:
+
+```text
+- Do tests exist for the change?
+- Do they test behavior (not implementation details)?
+- Are edge cases covered?
+- Do tests have descriptive names?
+- Would the tests catch a regression if the code changed?
+```
+
+### Step 3: Review the Implementation
+
+Walk through the code with the five axes in mind:
+
+```text
+For each file changed:
+1. Correctness: Does this code do what the test says it should?
+2. Readability: Can I understand this without help?
+3. Architecture: Does this fit the system?
+4. Security: Any vulnerabilities?
+5. Performance: Any bottlenecks?
+```
+
+### Step 4: Categorize Findings
+
+Label every comment with its severity so the author knows what's required vs
+optional:
+
+| Prefix                        | Meaning            | Author Action                                           |
+| ----------------------------- | ------------------ | ------------------------------------------------------- |
+| _(no prefix)_                 | Required change    | Must address before merge                               |
+| **Critical:**                 | Blocks merge       | Security vulnerability, data loss, broken functionality |
+| **Nit:**                      | Minor, optional    | Author may ignore — formatting, style preferences       |
+| **Optional:** / **Consider:** | Suggestion         | Worth considering but not required                      |
+| **FYI**                       | Informational only | No action needed — context for future reference         |
+
+This prevents authors from treating all feedback as mandatory and wasting time
+on optional suggestions.
+
+### Step 5: Verify the Verification
+
+Check the author's verification story:
+
+```text
+- What tests were run?
+- Did the build pass?
+- Was the change tested manually?
+- Are there screenshots for UI changes?
+- Is there a before/after comparison?
+```
+
+## Multi-Model Review Pattern
+
+Use different models for different review perspectives:
+
+```text
+Model A writes the code
+    │
+    ▼
+Model B reviews for correctness and architecture
+    │
+    ▼
+Model A addresses the feedback
+    │
+    ▼
+Human makes the final call
+```
+
+This catches issues that a single model might miss — different models have
+different blind spots.
+
+**Example prompt for a review agent:**
+
+```text
+Review this code change for correctness, security, and adherence to
+our project conventions. The spec says [X]. The change should [Y].
+Flag any issues as Critical, Important, or Suggestion.
+```
+
+## Dead Code Hygiene
+
+After any refactoring or implementation change, check for orphaned code:
+
+1. Identify code that is now unreachable or unused
+2. List it explicitly
+3. **Ask before deleting:** "Should I remove these now-unused elements: [list]?"
+
+Don't leave dead code lying around — it confuses future readers and agents. But
+don't silently delete things you're not sure about. When in doubt, ask.
+
+```text
+DEAD CODE IDENTIFIED:
+- formatLegacyDate() in src/utils/date.ts — replaced by formatDate()
+- OldTaskCard component in src/components/ — replaced by TaskCard
+- LEGACY_API_URL constant in src/config.ts — no remaining references
+→ Safe to remove these?
+```
+
+## Review Speed
+
+Slow reviews block entire teams. The cost of context-switching to review is less
+than the waiting cost imposed on others.
+
+- **Respond within one business day** — this is the maximum, not the target
+- **Ideal cadence:** Respond shortly after a review request arrives, unless deep
+  in focused coding. A typical change should complete multiple review rounds in
+  a single day
+- **Prioritize fast individual responses** over quick final approval. Quick
+  feedback reduces frustration even if multiple rounds are needed
+- **Large changes:** Ask the author to split them rather than reviewing one
+  massive changeset
+
+## Handling Disagreements
+
+When resolving review disputes, apply this hierarchy:
+
+1. **Technical facts and data** override opinions and preferences
+2. **Style guides** are the absolute authority on style matters
+3. **Software design** must be evaluated on engineering principles, not personal
+   preference
+4. **Codebase consistency** is acceptable if it doesn't degrade overall health
+
+**Don't accept "I'll clean it up later."** Experience shows deferred cleanup
+rarely happens. Require cleanup before submission unless it's a genuine
+emergency. If surrounding issues can't be addressed in this change, require
+filing a bug with self-assignment.
+
+## Honesty in Review
+
+When reviewing code — whether written by you, another agent, or a human:
+
+- **Don't rubber-stamp.** "LGTM" without evidence of review helps no one.
+- **Don't soften real issues.** "This might be a minor concern" when it's a bug
+  that will hit production is dishonest.
+- **Quantify problems when possible.** "This N+1 query will add ~50ms per item
+  in the list" is better than "this could be slow."
+- **Push back on approaches with clear problems.** Sycophancy is a failure mode
+  in reviews. If the implementation has issues, say so directly and propose
+  alternatives.
+- **Accept override gracefully.** If the author has full context and disagrees,
+  defer to their judgment. Comment on code, not people — reframe personal
+  critiques to focus on the code itself.
+
+## Dependency Discipline
+
+Part of code review is dependency review:
+
+**Before adding any dependency:**
+
+1. Does the existing stack solve this? (Often it does.)
+2. How large is the dependency? (Check bundle impact.)
+3. Is it actively maintained? (Check last commit, open issues.)
+4. Does it have known vulnerabilities? (`npm audit`)
+5. What's the license? (Must be compatible with the project.)
+
+**Rule:** Prefer standard library and existing utilities over new dependencies.
+Every dependency is a liability.
+
+## The Review Checklist
+
+```markdown
+## Review: [PR/Change title]
+
+### Context
+
+- [ ] I understand what this change does and why
+
+### Correctness
+
+- [ ] Change matches spec/task requirements
+- [ ] Edge cases handled
+- [ ] Error paths handled
+- [ ] Tests cover the change adequately
+
+### Readability
+
+- [ ] Names are clear and consistent
+- [ ] Logic is straightforward
+- [ ] No unnecessary complexity
+
+### Architecture
+
+- [ ] Follows existing patterns
+- [ ] No unnecessary coupling or dependencies
+- [ ] Appropriate abstraction level
+
+### Security
+
+- [ ] No secrets in code
+- [ ] Input validated at boundaries
+- [ ] No injection vulnerabilities
+- [ ] Auth checks in place
+- [ ] External data sources treated as untrusted
+
+### Performance
+
+- [ ] No N+1 patterns
+- [ ] No unbounded operations
+- [ ] Pagination on list endpoints
+
+### Verification
+
+- [ ] Tests pass
+- [ ] Build succeeds
+- [ ] Manual verification done (if applicable)
+
+### Verdict
+
+- [ ] **Approve** — Ready to merge
+- [ ] **Request changes** — Issues must be addressed
+```
+
+## Common Rationalizations
+
+| Rationalization                      | Reality                                                                                                                   |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| "It works, that's good enough"       | Working code that's unreadable, insecure, or architecturally wrong creates debt that compounds.                           |
+| "I wrote it, so I know it's correct" | Authors are blind to their own assumptions. Every change benefits from another set of eyes.                               |
+| "We'll clean it up later"            | Later never comes. The review is the quality gate — use it. Require cleanup before merge, not after.                      |
+| "AI-generated code is probably fine" | AI code needs more scrutiny, not less. It's confident and plausible, even when wrong.                                     |
+| "The tests pass, so it's good"       | Tests are necessary but not sufficient. They don't catch architecture problems, security issues, or readability concerns. |
+
+## Red Flags
+
+- PRs merged without any review
+- Review that only checks if tests pass (ignoring other axes)
+- "LGTM" without evidence of actual review
+- Security-sensitive changes without security-focused review
+- Large PRs that are "too big to review properly" (split them)
+- No regression tests with bug fix PRs
+- Review comments without severity labels — makes it unclear what's required vs
+  optional
+- Accepting "I'll fix it later" — it never happens
+
+## Post-Green Refactor Pass
+
+Review's sibling discipline is the **behaviour-preserving refactor** that drives
+CRAP (Change Risk Anti-Patterns) and duplication down _after_ the code is green
+— the pass wired in as the opt-in `delivery.refactorStage` checkpoint. It
+optimises for the measured CRAP and duplication axes the baselines ratchet, not
+for subjective readability, and it never runs from red.
+
+**When to run:** a baseline report flags a high-CRAP function that is already
+well-covered (so the lever is complexity, not coverage); the same logic is
+duplicated across two or more files and the copies are drifting; or the
+`delivery.refactorStage` checkpoint fires after gates pass and before a Story
+closes. **When NOT to:** before tests are green (write/fix tests first), or when
+a function's CRAP is high because it is _uncovered_ — that is a missing-test
+problem, so drive it with the TDD cycle in
+[`.agents/rules/testing-standards.md`](../../../rules/testing-standards.md).
+
+```text
+Confirm green + baseline  →  pick highest-CRAP / largest dup
+        ▲                                  │
+        │                                  ▼
+  re-run gates, confirm   ◄──  refactor   ◄──  comprehend the target
+  CRAP↓ / maint↑, tests pass   (one change)    (call sites + tests)
+```
+
+1. **Baseline.** Confirm green and capture current CRAP and maintainability
+   (`node .agents/scripts/check-baselines.js`) — your do-no-harm reference.
+2. **Target by measurement.** Pick the highest-CRAP well-covered function, or
+   the largest verbatim duplication. Work worst-first.
+3. **Comprehend before you touch (Chesterton's Fence).** Read the call sites and
+   the tests that pin the behaviour first; an "unnecessary" abstraction may
+   exist for testability or extensibility.
+4. **Refactor one step.** Extract a focused function, flatten nesting into guard
+   clauses, replace a nested ternary / boolean-flag param, or extract a single
+   shared helper for the duplication (dedup the _behaviour_, not just the text —
+   look-alike blocks that encode different responsibilities stay separate).
+5. **Verify.** Re-run the affected tests (unmodified) and the baselines. CRAP
+   must not rise, maintainability must not fall, tests must pass. If a test
+   needed editing, revert — behaviour changed.
+
+Keep each refactor an isolated, reviewable commit separate from feature or fix
+work, refactor only the targeted functions/duplications (no drive-by rewrites),
+and leave no dead code behind (unused imports, orphaned helpers).
+
+## Verification
+
+After review is complete:
+
+- [ ] All Critical issues are resolved
+- [ ] All Important issues are resolved or explicitly deferred with
+      justification
+- [ ] Tests pass
+- [ ] Build succeeds
+- [ ] The verification story is documented (what changed, how it was verified)
+
+After a post-green refactor pass:
+
+- [ ] The suite was green before and after, with **no test modifications**
+- [ ] CRAP did not rise and maintainability did not fall on any touched file
+      (baselines re-run and compared)
+- [ ] No gate, floor, or coverage threshold was loosened
+- [ ] Duplication was removed at the root (one helper), not just locally patched
+- [ ] Each refactor is an isolated commit, separate from feature or fix work