tibursocampos STOP - Read before ANY tool call
- Read
E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/rules/guardrails.mdc - Read
_shared/sdd-artifacts/SESSION.md; load session-state for$Cwd - If the relevant gate is not approved: STOP - ask user (pt-BR) - do NOT Write/Shell
- SDD/develop skills: after ONE step/task, STOP session - handoff only
- This skill body is English; user-facing prompts may be (pt-BR)
Step -1 - Gate check (report in chat before continuing)
Gate check:
[ ] guardrails.mdc read
[ ] SESSION.md read; session-state loaded
[ ] PIPELINE.md read (SDD skills only)
[ ] User confirmed current action (sim)
-> If any unchecked: STOP
Trigger
Invoke when the user asks for: /code-review, review this PR, code review.
Review mode (mandatory choice - no silent default):
| Mode | Explicit invoke examples |
|---|---|
| Single | single, single-angle, simples |
| Multi-angle | multi-angle, multi-ângulo, or ângulos: qualidade, aceite, segurança (subset allowed) |
If the invocation does not name single or multi-angle: STOP after gate check (-1) / before deep diff analysis - ask once (pt-BR) and wait. Do not assume single. Do not assume multi.
Modo de code-review?
1) single - um revisor (passos -1..8)
2) multi-ângulo - qualidade + aceite + segurança (ou diga o subset)
Outcome
A structured review report with severity tiers (critical / important / nice-to-have) and a clear decision: Approved, Approved with reservations, or Changes required. Write the report in pt-BR in chat-aligned reviews (technical terms may stay in English). Does not modify code unless the user asks for fixes in a follow-up.
Required input
| Input | Rule |
|---|---|
| Base branch | main, develop - ask once if missing |
| Feature branch | Current branch or named branch |
| PRD / PLAN (SDD) | Optional in invocation; resolve in step 0.5 if omitted (see reference.md section SDD artifact resolution) |
| Review mode | Explicit in invoke or answer to step 0.25 - never silent default |
Ask the user only after step 0.5 if zero or multiple PRD/PLAN pairs remain ambiguous. For a quick review without SDD artifacts, base branch + changed paths suffice after 0.5 reports no artifacts.
Lazy-load (only when needed)
| When | Path (after sync) |
|---|---|
| SDD artifact discovery (step 0.5) | E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/_shared/sdd-artifacts/STORAGE.md |
| Repo context | E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/_shared/developer-common/step-0-context.md |
| Before code analysis (.NET) | E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/_shared/dotnet-guidelines/clean-architecture.md, csharp-patterns.md |
| Pre-PR gate (.NET) | E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/_shared/dotnet-guidelines/checklist.md |
| .NET coverage report | E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/test-coverage/reference.md (when PRD/user/PLAN requires coverage) |
| Principles | E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/_shared/code-guidelines/principles/principles-cheatsheet.md |
| Caveman Mode (if active) | E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/_shared/caveman/CAVEMAN.md - Full cap |
| Final Git hygiene | E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/_shared/developer-common/step-7-checklist.md |
Spawn native vs fallback (capability subagents) |
E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/_shared/agents/SPAWN.md |
| Report template | reference.md (this skill) |
Prefer project docs/standards/ or repo AGENTS.md over generic guidelines when both exist.
Do not preload code-guidelines/languages/** or corporate static-analysis workflows.
Process
Step -1b - Caveman Mode (Full cap)
- Read
E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/sdd/preferences.json(create{ "caveman_mode": false, "caveman_level": "full" }if missing). - If
caveman_modeis false: continue without compression. - If true: load
E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/_shared/caveman/CAVEMAN.md; apply Full participation cap + prefscaveman_level(Lite skills never escalate); show once:[Caveman] Modo ativo (respostas compactas, level={effective}). Digite caveman off para desativar. - Honor
caveman on|off|status|lite|full|ultra(andstop caveman/normal mode) during the session. - Auto-Clarity + never-compress gates/drafts/paths per
CAVEMAN.md.
0. Workspace
Confirm target repo (not this toolkit repo unless that is the subject). Detect stack (*.sln -> .NET; angular.json -> Angular). Read AGENTS.md / README.md. Load dotnet-guidelines only for .NET reviews.
0.25 Review mode (single vs multi-angle)
Resolve mode from the invocation or from the user's answer to the Trigger prompt.
| Signal in invoke / reply | Mode |
|---|---|
single / single-angle / simples / 1 |
Single reviewer (steps -1..8 only) |
multi-angle / multi-ângulo / 2 / named ângulos: … |
Multi-angle (see section below) |
If still unset: STOP - ask the Trigger prompt (pt-BR) - do not continue to 0.5/1 until answered. Novice-friendly: never pick a default for them.
0.5 Resolve SDD artifacts
Load STORAGE.md. Follow reference.md section SDD artifact resolution (manifest, globs repo + E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/sdd/<repo-id>/, pair by NNN). Use full paths in the report. If one PRD/PLAN pair -> read both before the diff review. If none after a full search -> note SDD limitation in the report (technical review only). If ambiguous -> ask once in pt-BR with numbered options.
1. Scope the diff
git fetch origin # when remote comparison is needed
git diff <base>...<head> --stat
git diff <base>...<head>
git log <base>..<head> --oneline
Default <head> to current branch. List files; confirm with user before deep review if the set is large.
2. SDD traceability (when artifacts found or user provided)
Skip this section only when step 0.5 found no PRD/PLAN (document limitation - do not claim artifacts do not exist).
- PLAN progress bar and step statuses match completed work
- Each Completed / Concluido step has deliverables checked; no Pending steps with code already merged
- PRD acceptance criteria mapped to implementation and tests
Flag PLAN/PRD drift as important (not necessarily blocking if scope is otherwise correct).
3. Standards and guidelines
- Project
docs/standards/or equivalent E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/_shared/dotnet-guidelines/for .NET (layers, tests: xUnit, Moq, Shouldly,Should_<Result>_When_<Condition>)- Principles cheatsheet when installed
4. Code analysis
Review changed files for:
| Area | Focus |
|---|---|
| Correctness | Logic, edge cases, error handling |
| Architecture | Layer boundaries, DI, no domain -> infrastructure leaks |
| Tests | Behavior covered; meaningful assertions; no trivial tests |
| Security | Secrets, injection, authz, sensitive logs |
| Performance | N+1, unbounded work, missing async where I/O |
| Maintainability | Naming, method size, duplication; magic values / structure - see csharp-patterns.md normative sections |
Use the checklists in reference.md - do not paste full guideline bodies into the report.
5. Run verification (when feasible)
| Stack | Commands |
|---|---|
| .NET | dotnet build, dotnet test (scoped if large) |
| .NET coverage | /test-coverage when PRD, PLAN, or user sets a coverage target (default threshold 80% on changed production files) |
| Node | npm run build, npm test per project scripts |
For .NET with a coverage target: run test-coverage before final decision; paste the summary into the report section Testes (see reference.md). If test-coverage reports Fail (< threshold), treat as Changes required unless the user documents an accepted exception.
Record pass/fail in the report. Missing local run -> note as limitation.
6. Decision
| Decision | When |
|---|---|
| Approved | PRD/PLAN met; no critical issues; tests/build green; coverage >= threshold when target applies |
| Approved with reservations | Minor gaps; no security/correctness blockers; coverage at or above threshold with documented gaps below 100% target |
| Changes required | Critical bugs/security; PRD gaps; build/test failures; coverage < threshold on changed files when target applies |
7. Write report
Use the template in reference.md (repo: skills/code-review/reference.md; installed: E:/Source/Repos/agent-dev-toolkit/scripts/validation/fixtures/zcode-install-root/skills/code-review/reference.md).
Be specific: path:line, explain why, suggest how to fix. Include positives.
8. Optional PR (user-driven)
Create a PR only when the user asks and review is not Changes required:
- Ensure the feature branch is pushed (
/pushafter confirmation if needed). - Hand off to
/open-github-pr(do not open the GitHub web UI compare flow from this skill;/open-github-prowns CLI/templates/confirmation/auto-merge).
No MCP work-item linking or mandatory corporate PR templates.
Multi-angle mode (when chosen)
Run only after step 0.25 resolved to multi-angle (explicit flag or user chose option 2 / named angles). Single mode = steps -1..8 as one reviewer - never implied by silence.
SPAWN first: load SPAWN.md; consult capability subagents. Prefer parallel Task when native; if subagents=none or Task unavailable → fallback sequential in-parent angles (same checklists; never hard-fail). Concurrent Task cap stays within orchestrate ≤4 from SPAWN.md (multi-angle uses ≤3 angles).
When multi-angle:
- After scoping the diff (step 1) and resolving SDD artifacts (0.5), if
subagents=native: spawn up to 3 parallel Task subagents - one per requested angle (default all three if user said multi without subset):- quality - correctness, architecture, tests, maintainability, performance
- acceptance (aceite) - PRD criteria / PLAN deliverables vs the diff
- security - AuthZ/AuthN, injection, secrets/PII, dangerous defaults (hints:
_shared/agents/prompts/security.md) Else (fallback): run those angles in-parent sequentially (same prompts/checklists; no Task required).
- Parent synthesizes Task outputs (or in-parent angle notes) into one report using the existing
reference.mdtemplate (map findings to críticos / importantes / nice-to-have). - Decision matrix (step 6) and coverage gates are unchanged - multi-angle does not change decision semantics, does not auto-block O3 or the SDD pipeline, and does not require separate blind-reviewer skills.
See reference.md section Multi-angle mode for invoke examples and per-angle checklists.
Must not
- Write or update PRD/PLAN files (hand off to
/sdd-spec//sdd-plan) - Auto-merge, auto-approve, or rewrite code without user request
- Work-item tracker APIs, external PR platform APIs, or obsolete guideline paths
- Block on coverage only when no target applies - when PRD, PLAN, user, or a
test-coveragereport defines a threshold (default 80% on changed production files), treat below threshold as Changes required - Paste entire guideline files into the review output
- Claim no PRD/PLAN or skip step 0.5 / SDD traceability without searching all locations in
STORAGE.md - Assume single or multi-angle when the user did not name either (always ask - step 0.25)
- Force multi-angle as a pipeline gate, or create separate mandatory blind-reviewer skills
- Hard-fail multi-angle when
subagentsisnoneor Task is unavailable (use fallback sequential in-parent perSPAWN.md) - Paste guideline packs into Task child prompts
- AI co-author trailers - in any form. Under NO circumstances should you include
Co-authored-by: Cursor <cursoragent@cursor.com>,Co-authored-by: Antigravity, or any other AI agent attribution in commit messages or PR descriptions.
Handoff
| Situation | Next |
|---|---|
After O3 (orchestrate-develop) completes |
/code-review - skill asks single vs multi if not specified; never required as pipeline gate |
| New feature / PRD from review findings | /sdd-spec - paste or summarize review items; do not write PRD in this skill |
| Coverage below threshold | /test-coverage -> then /dotnet-developer or /sdd-develop |
| Fixes needed | User or /sdd-develop / /dotnet-developer |
| Commit fixes | /commit |
| All SDD steps done + approved | User opens PR in GitHub UI or merges per repo policy |