nurosys-agents 2.0.0

package/.agent/monolith/skills/code-reviewer/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: code-reviewer
+description: Full-stack code review for backend changes on the current branch. Reads all project-memory docs, audits changed files against the constitution/quality-playbook/auth-model/architecture/models, and writes a structured REVIEW_REPORT to documentation/reports/ (or the active feature folder). Trigger on any "review my changes", "review this branch", "do a code review", or "review <feature>" request.
+---
+
+# Skill: code-reviewer
+
+Use this skill to perform a thorough, standards-aligned code review of all uncommitted or branch-level changes. The output is a structured review report written to the project's `documentation/reports/` directory (or the active feature folder when one is clearly identified).
+
+---
+
+## When to trigger
+
+- User says "review my changes", "do a code review", "review this branch", or similar.
+- User asks for a review of a specific feature or module before merging.
+- Used automatically at the end of a feature-module implementation workflow.
+
+---
+
+## Phase 1 — Understand the change surface
+
+### 1.1 Identify changed files
+
+Run the following to understand what is in scope:
+
+```bash
+git status
+git diff --name-only HEAD
+git diff --name-only --cached
+```
+
+For a branch comparison against main:
+
+```bash
+git diff --name-only main...HEAD
+```
+
+Collect:
+- All modified, added, and deleted files.
+- The active branch name (to infer feature name and milestone if present).
+- Whether changes are staged, unstaged, or committed ahead of main.
+
+### 1.2 Infer feature and milestone
+
+Extract from the branch name or the changed file paths:
+- **Feature name**: the slug after `feature/`, `feat/`, or derived from the dominant changed folder under `src/apis/` (e.g. `influencer-discovery`).
+- **Milestone**: if module files exist under `documentation/features/<feature>/`, identify the highest module number being reviewed (e.g. `M3`). Otherwise use `M0` or omit.
+
+### 1.3 Use graph tools first (per CLAUDE.md)
+
+Before reading any file, use the code-review-graph MCP tools for efficient structural analysis:
+
+1. `get_minimal_context(task="<review summary>")` — **always call this first** to orient the graph.
+2. `detect_changes` — get a risk-scored diff summary of what changed and why it matters.
+3. `get_review_context` — retrieve token-efficient source snippets for changed symbols.
+4. `get_impact_radius` — for any modified service/module, understand blast radius.
+5. `get_affected_flows` — identify which execution paths are affected.
+6. `query_graph(pattern="tests_for")` — for any high-risk function, verify test coverage.
+
+Fall back to direct file reads only when the graph does not cover what you need.
+
+**Token efficiency**: use `detail_level="minimal"` on all graph calls; only escalate to `"standard"` when minimal is insufficient. Target ≤5 graph tool calls for the structural analysis phase.
+
+---
+
+## Phase 2 — Load project-memory context
+
+Read all of the following files in full before reviewing any code. These define the non-negotiable constraints for this codebase.
+
+| File | Purpose |
+|------|---------|
+| `project-memory/constitution.md` | Non-negotiable rules: structure, security, validation, auth, DI, SQL, error handling |
+| `project-memory/quality-playbook.md` | High-signal check patterns with symptoms, root causes, and preferred fixes |
+| `project-memory/auth-model.md` | JWT flow, guard chain, RBAC entities, tenant/resource scoping |
+| `project-memory/architecture.md` | System-level architecture decisions and module topology |
+| `project-memory/models.md` | Domain model inventory: Sequelize entities, associations, field contracts |
+| `project-memory/repo-map.md` | Module layout, naming conventions, reusable component registry |
+| `project-memory/core-memory.md` | Historical implementation decisions and completed module record |
+| `project-memory/README.md` | Index of all project-memory docs |
+
+If a file does not exist, skip it and note the omission in the review.
+
+---
+
+## Phase 3 — Review the changed code
+
+For each changed file, perform the following checks. Record every finding, tagged by severity.
+
+### 3.1 Structural alignment (Constitution §Project structure, repo-map.md §Module layout)
+
+- [ ] New feature modules follow the directory structure and naming convention defined in `project-memory/repo-map.md`.
+- [ ] All required files for this project type are present (see repo-map for the checklist: e.g., DB-backed features might need `.model.ts`, `.service.ts`, `.dto.ts`, etc.).
+- [ ] New models/entities are registered per `project-memory/repo-map.md` (e.g., in a models registry file).
+- [ ] Feature module is wired into the module tree per repo-map (e.g., imported in a root APIs module or feature module).
+- [ ] No new file duplicates functionality already documented in `project-memory/repo-map.md`.
+
+### 3.2 Security and auth (Constitution, quality-playbook)
+
+- [ ] Every endpoint has an explicit auth decision: protected (requires auth/permission) or intentionally public.
+- [ ] Protected endpoints use your project's auth guard/middleware (see `project-memory/auth-model.md`).
+- [ ] Permission/authorization checks happen both at endpoint level and service level where applicable.
+- [ ] Service/query layer enforces ownership/tenant scoping using authenticated context, never client-supplied IDs.
+- [ ] Identity and tenant context come from authenticated request context, never from request body/query.
+- [ ] No secrets or config values hardcoded in code; use your project's config service/mechanism.
+
+### 3.3 Input validation (Constitution, quality-playbook)
+
+- [ ] All endpoints validate inputs (body, query, path params) using your project's validation mechanism (e.g., DTOs, validation pipes, decorators).
+- [ ] No raw request data passed to services/repositories/queries; always validate at the boundary.
+- [ ] Unknown/extra fields are rejected for auth-sensitive and data-sensitive endpoints (explicit allowlist or default deny).
+
+### 3.4 Dependency injection and module wiring (Constitution, quality-playbook)
+
+- [ ] DI tokens/identifiers are defined consistently and reused across the module.
+- [ ] No new circular dependencies; if DI needs bidirectional wiring, it's explicitly documented.
+- [ ] Module/package imports and exports are correctly wired for all dependencies.
+- [ ] Controllers/handlers are thin; business logic lives in services, not at the boundary.
+
+### 3.5 Error handling (Constitution)
+
+- [ ] Client errors (validation, auth, resource not found) use appropriate status codes (4xx), not 500.
+- [ ] Errors are not silently swallowed; all error paths are logged or explicitly documented.
+- [ ] Error responses follow your project's consistent envelope shape (see `project-memory/constitution.md`).
+
+### 3.6 SQL and query safety (Constitution §9–11)
+
+- [ ] All user-influenced values are parameterized (use your ORM/query builder's parameterization mechanism, never string interpolation).
+- [ ] No string concatenation of request input into SQL templates.
+- [ ] Raw queries (if used) employ parameterization consistently with your project's query library (see `project-memory/repo-map.md` for patterns).
+- [ ] Row-level security applied via server-side tenant/ownership predicates, never from client-supplied IDs.
+
+### 3.7 Logging and PII (Constitution)
+
+- [ ] No secrets, tokens, passwords, credentials, or sensitive user data logged.
+- [ ] No full request/response bodies logged for auth-sensitive or PII-containing endpoints.
+- [ ] Logged context is actionable: route identifier, request/trace ID, function/service, error type/message.
+
+### 3.8 Dependencies (Constitution)
+
+- [ ] No new external dependency added without explicit justification (why not use existing libs?).
+- [ ] Prefer reusing your project's existing libraries and frameworks over adding new ones.
+
+### 3.9 Caching (Constitution)
+
+- [ ] Cache keys derived from canonicalized inputs using your project's cache key strategy.
+- [ ] Cache bypass/refresh happens only where freshness is explicitly required.
+- [ ] No accidental changes to cache key derivation or TTL semantics that would break stale invalidations.
+
+### 3.10 Model and domain alignment (project-memory/models.md)
+
+- [ ] New data models follow your project's ORM conventions and naming rules (see repo-map and models doc).
+- [ ] Table/entity metadata is explicit (table names, timestamps, field-to-column mappings).
+- [ ] Associations (foreign keys, relationships) are correctly defined; no orphaned or unmapped foreign keys.
+- [ ] Field naming is consistent with project conventions (e.g., snake_case in DB, camelCase in code).
+
+### 3.11 Architecture alignment (project-memory/architecture.md)
+
+- [ ] Changes respect the module topology and layers described in your architecture doc.
+- [ ] No new unexpected coupling between modules without documented rationale (see repo-map).
+- [ ] External-service integration (APIs, queues, caches, etc.) follows your project's established patterns.
+
+---
+
+## Phase 4 — Determine the output location
+
+Choose the report location based on context:
+
+| Condition | Output path |
+|-----------|-------------|
+| Active feature with a folder under `documentation/features/<feature>/` | `documentation/features/<feature>/REVIEW_REPORT_<feature>_<milestone>.md` |
+| General / no clearly scoped feature folder | `documentation/reports/REVIEW_REPORT_<feature>_<milestone>.md` |
+| No feature identifiable | `documentation/reports/REVIEW_REPORT_<branch-slug>.md` |
+
+Name the file using:
+- `<feature>` = feature slug in your project's naming convention (e.g., kebab-case).
+- `<milestone>` = module/phase label if applicable (e.g., `M3`), otherwise omit.
+
+---
+
+## Phase 5 — Write the review report
+
+Save the review report to the path determined in Phase 4. Use this template:
+
+```markdown
+# Backend Code Review Report
+
+## Feature
+`<feature-name>` — <short description of the change being reviewed>
+
+## Branch
+`<branch-name>`
+
+## Scope Reviewed
+<Bullet list of changed files/folders reviewed and what each covers>
+
+---
+
+## Findings
+
+### BLOCKER
+<List each blocker finding with:>
+- **File**: `path/to/file.ts` (line N if known)
+- **Issue**: What is wrong.
+- **Rule**: Which constitution / quality-playbook rule is violated.
+- **Fix**: Minimum change needed to resolve.
+
+*(none)* if no blockers.
+
+### HIGH
+<Same format. HIGH = must fix before merge, not necessarily a blocker today.>
+
+*(none)* if none.
+
+### MEDIUM
+<Same format. MEDIUM = should fix in this PR; acceptable to defer with documented rationale.>
+
+*(none)* if none.
+
+### LOW / SUGGESTION
+<Same format. LOW = nice-to-have improvements or style alignment.>
+
+*(none)* if none.
+
+---
+
+## Architecture Alignment
+<1–3 bullet points on how well the changes align with project-memory/architecture.md and repo-map.md. Note any deviations.>
+
+## Auth and Security Summary
+<1–2 sentences confirming auth coverage or identifying remaining gaps.>
+
+## Quality Gate Status
+
+| Gate | Status | Notes |
+|------|--------|-------|
+| TypeScript compile (`npx tsc --noEmit`) | pass / fail / not run | |
+| Lint (`npm run lint`) | pass / fail / not run | |
+| Unit tests | pass / fail / not run | |
+| E2E tests | pass / fail / not run | |
+
+Run the gates that are feasible given the current environment. Report blocked gates and whether they are pre-existing failures unrelated to these changes.
+
+## Recommendation
+
+**APPROVE** / **APPROVE WITH CONDITIONS** / **REQUEST CHANGES**
+
+<1–2 sentences explaining the recommendation and any required follow-up.>
+```
+
+---
+
+## Phase 6 — Report to user
+
+After writing the file, output to the user:
+
+1. The full path of the written report.
+2. A concise inline summary:
+   - Number of blockers, high, medium, low findings.
+   - Overall recommendation (APPROVE / APPROVE WITH CONDITIONS / REQUEST CHANGES).
+   - Any critical finding that must be addressed before merge.
+
+---
+
+## Quality gates for the review itself
+
+Before finalizing the report, verify:
+
+- [ ] Every finding links to a specific constitution/quality-playbook rule or project-memory doc section.
+- [ ] Every finding names the exact file (and line where possible).
+- [ ] The report does not describe what code does — it states what is wrong and what the fix is.
+- [ ] Auth and validation coverage has been explicitly confirmed or flagged, not assumed.
+- [ ] No findings are added for purely stylistic preferences without a rule citation.
+- [ ] The gate status table reflects actual command output, not assumptions.
+
+---
+
+## Notes
+
+- This skill reads project-memory docs but does NOT modify them. After implementation modules, `core-memory.md` is updated by the feature-module-runner, not this skill.
+- If this review is triggered mid-module (not post-implementation), findings should feed back into the implementation, not the merge decision.
+- For auth-heavy changes, complement this review with `.agent/skills/auth-and-permissions/SKILL.md`.