arkaos 4.17.0 → 4.19.0

package/departments/dev/skills/click-path-audit/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: dev/click-path-audit
+description: >
+  Simulates every interactive handler call-by-call to find bugs a normal
+  read skips over — shared-state side effects, handlers that silently undo
+  each other, and async races — then checks the final UI state matches
+  what the control promises. TRIGGER: "/dev click-path-audit", "the button
+  does nothing", "state side effects", "handlers cancel each other", "why
+  is the UI wrong after clicking", "o botão não faz nada", "audita o fluxo
+  de cliques"; run on an interactive component whose behaviour is wrong but
+  whose code looks right. SKIP: general pre-merge review ->
+  dev/code-review wins; visual/layout/brand review ->
+  brand/design-review wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+# Click-Path Audit — `/dev click-path-audit`
+
+> **Agent:** Diana (Senior Frontend Developer) | **Framework:** Handler state-tracing, shared-state side-effect analysis
+
+Some interface bugs survive every check that looks at one thing at a time.
+Each handler compiles, each function returns the right type, each call
+works when you test it alone — and the button still does the wrong thing,
+because the second call quietly resets the state the first one set. This
+lens catches those by simulating the handler on paper: it walks the calls
+in the order they run and tracks what each reads, writes, and resets in
+shared state, so a cancelling side effect shows up before a user ever
+clicks.
+
+## The bug this catches
+
+An "Apply filters" button called `setFilters(next)` and then, to close the
+panel, `resetPanel()`. Each worked alone — but `resetPanel` cleared the
+draft filter state as part of tidying up, so the store ended with the old
+filters and the list never changed. No type error, no crash, no failing
+unit test; the two setters simply fought and the second won. Walking the
+handler's calls in order puts the cleared write next to the one it
+cancelled, and the bug is visible without ever running the app.
+
+## Process
+
+For every interactive touchpoint in scope (`onClick`, `onSubmit`, `onChange`, effects):
+
+1. **Identify** the handler.
+2. **Trace** each call it makes, in order.
+3. For each call record: what shared state it **reads**, what it **writes**, and any **side effect** — especially a state it clears or resets that it does not obviously own.
+4. **Check** whether any later call undoes a state change an earlier call made.
+5. **Check** the final state matches what the control's label promises.
+6. **Check** for races — async calls whose resolution order changes the outcome (a stale response overwriting a fresh one).
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- two calls in one handler that write the same store slice → which one wins, and is that intended
+- a setter with a side effect that resets unrelated state (a `select`/`reset`/`clear` that touches more than its name implies) → the earlier change it silently undoes
+- an `await` inside a handler with no guard against an out-of-order resolution → the stale-overwrite race
+
+## Output
+
+```markdown
+## Click-Path Report
+
+**Scope:** {component / area audited}
+
+### {control / handler} — {file}:{line}
+| # | Call | Reads | Writes | Side effect |
+|---|------|-------|--------|-------------|
+| 1 | {fn} | {state} | {state} | {reset/clear, or none} |
+| 2 | {fn} | {state} | {state} | {undoes call 1's write?} |
+
+**Promised by label:** {what the user expects} · **Actual final state:** {what happens}
+**Verdict:** {works / silently broken} · **Fix:** {reorder, isolate the side effect, guard the race}
+```

package/departments/dev/skills/laravel-review/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: dev/laravel-review
+description: >
+  Laravel/PHP review against ArkaOS conventions — mass assignment, N+1
+  queries, Blade XSS, business logic leaking into controllers, missing
+  FormRequests, and strict-types gaps — with the fix each one needs.
+  TRIGGER: "/dev laravel-review", "review this Laravel", "review the PHP",
+  "revê este controller", "revê o Eloquent", "isto está seguro em
+  Laravel?", any diff touching *.php, Blade, or Eloquent models. SKIP:
+  language-agnostic pre-merge review -> dev/code-review wins; database
+  schema/migration design -> dev/db-design wins; a security audit of the
+  whole app -> dev/security-audit wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# Laravel Review — `/dev laravel-review`
+
+> **Agent:** Gonçalo (Laravel Specialist) | **Framework:** Laravel conventions, OWASP, ArkaOS Services+Repositories standard
+
+Laravel makes the wrong thing easy: `create($request->all())` is one line
+and a mass-assignment hole, an Eloquent relation in a Blade loop is one
+property access and an N+1, `{!! $x !!}` is shorter than the escaped form
+and an XSS. This review reads a PHP diff for the specific ways the
+framework's convenience turns into a defect, and holds it to the ArkaOS
+Laravel standard — Services and Repositories, FormRequests everywhere,
+`declare(strict_types=1)`, not just to PSR-12.
+
+## Review Priorities
+
+### Critical — Security
+- **Mass assignment**: `create($request->all())` or `$guarded = []` → whitelist `$fillable`, or pass `$request->validated()` from a FormRequest.
+- **SQL injection**: `DB::raw()`/`whereRaw()`/string-interpolated queries with user input → parameterised bindings or Eloquent.
+- **Blade XSS**: `{!! $userInput !!}` without HTMLPurifier → `{{ }}`, or purify explicitly.
+- **Command/path**: `exec`/`shell_exec`/`system` or `Storage` paths from user input → validate and sanitise.
+- **Unvalidated uploads**: no MIME/size/extension check on file inputs.
+- **Weak crypto / secrets**: MD5 for passwords, hardcoded keys.
+
+### Critical — Error handling
+- **Swallowed exceptions**: `catch (\Throwable $e) {}` with no log and no re-throw.
+- **Missing validation**: a controller action with no FormRequest and no inline rules.
+
+### High — ArkaOS Laravel standard
+- **Business logic in controllers** → extract to a Service or Action; the controller orchestrates, it does not decide.
+- **Data access outside a Repository** where the ecosystem uses them.
+- **No FormRequest** on a write endpoint → `$request->validated()`, never `$request->all()`.
+- **Missing `declare(strict_types=1)`** in non-view PHP; untyped public method params/returns.
+- **N+1**: an Eloquent relation accessed in a loop or serialisation with no `with()`/`$with`.
+- **Missing `$fillable`/`$casts`** on models; **missing Feature test** (`RefreshDatabase`) on the changed behaviour.
+
+## Process
+
+1. `git diff -- '*.php' '*.blade.php'` to scope the change.
+2. Run PHPStan/Pint if configured — read their output, do not just report their absence.
+3. Read each changed controller/model/service against the priorities, heaviest first.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- `$request->all()` reaching a `create`/`update`/`fill` → the mass-assignment hole; name the fields it exposes
+- a relation accessed inside `@foreach` or an API Resource with no eager load → the N+1 and the `with()` that fixes it
+- a controller method over ~15 lines carrying query + business logic → the Service/Action to extract
+
+## Output
+
+```markdown
+## Laravel Review
+
+**Scope:** {changed PHP / Blade}
+**Verdict:** {APPROVED / CHANGES REQUESTED}
+
+### Critical
+- [ ] {file}:{line} — {the hole} → {the fix}
+
+### High (ArkaOS standard)
+- [ ] {file}:{line} — {the convention broken} → {the fix}
+
+### Positive
+{what follows the standard well}
+```

package/departments/dev/skills/pr-test-analyzer/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: dev/pr-test-analyzer
+description: >
+  Judges whether a PR's tests would catch the change breaking — maps
+  changed code to its tests, finds untested paths and edge cases, flags
+  assertion-free and flaky tests, and ranks the gaps by blast radius.
+  TRIGGER: "/dev pr-test-analyzer", "test coverage of this PR", "are these
+  tests enough", "behavioural coverage", "test gaps", "os testes cobrem
+  isto?", "isto está bem testado?"; run on a diff before approving its
+  merge. SKIP: general code review -> dev/code-review wins; writing the
+  missing tests -> dev/tdd-cycle wins; error-handling review ->
+  dev/silent-failure-hunter wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# PR Test Analyzer — `/dev pr-test-analyzer`
+
+> **Agent:** Rita (QA Engineer) | **Framework:** Behavioural coverage, test-quality over line-coverage
+
+Coverage is a measure of which lines ran, and it is routinely mistaken for
+a measure of whether the change is safe. A PR can add a feature, run every
+new line through one happy-path test that asserts almost nothing, and post
+a green 100%. This lens reads the diff and its tests side by side and holds
+them to the only standard that matters at merge time: if the change were
+wrong, would a test go red?
+
+## Analysis
+
+### 1. Map changed code to tests
+- List the functions, classes, and branches the diff added or altered.
+- Locate the tests that exercise each. Name the changed paths with **no** test.
+
+### 2. Behavioural coverage
+- Does each new behaviour have a test that would fail if the behaviour broke?
+- Are the edge cases covered — empty input, boundary values, the error path, not just the success path?
+- Are the integrations the change touches (db, queue, external call) exercised, or only mocked away?
+
+### 3. Test quality
+- Flag tests that assert nothing beyond "it did not throw" — a green test that proves nothing.
+- Flag flaky patterns: time/order dependence, shared mutable state, sleeps.
+- Check that test names describe the behaviour, so a failure reads as a spec.
+
+### 4. Rank the gaps
+Rate each gap by the blast radius of the bug it would let ship:
+critical (data loss, auth, money), important (a real feature path),
+nice-to-have (a defensive branch unlikely to trigger).
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a changed function with no test at all → critical or important by its blast radius; name it
+- a new test with no assertion (or only `assert not raises`) → it proves nothing; say what it should assert
+- an error/exception path added in the diff with only the happy path tested → the failure that ships untested
+
+## Output
+
+```markdown
+## PR Test Report
+
+**Diff:** {files / functions changed}
+**Verdict:** {tests adequate to merge? yes / gaps below}
+
+### Coverage summary
+{what is covered well, in one or two lines}
+
+### Critical gaps
+- {file}:{func} — {the behaviour with no failing test} → {the test to add}
+
+### Test-quality issues
+- {file}:{test} — {assertion-free / flaky} → {fix}
+
+### Positive
+{what the tests do genuinely well}
+```

package/departments/dev/skills/python-review/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: dev/python-review
+description: >
+  Python review against ArkaOS conventions — missing type hints, mutable
+  default arguments, bare excepts, unvalidated boundaries, injection, and
+  Pydantic/FastAPI mistakes — with the fix each needs. TRIGGER: "/dev
+  python-review", "review this Python", "review the FastAPI", "revê o
+  Python", "revê este endpoint", "isto está pythonico?", any diff touching
+  *.py. SKIP: language-agnostic pre-merge review -> dev/code-review wins;
+  pytest coverage of the change -> dev/pr-test-analyzer wins; swallowed-error
+  hunt across the codebase -> dev/silent-failure-hunter wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# Python Review — `/dev python-review`
+
+> **Agent:** Diogo (Python Backend Specialist) | **Framework:** Type hints, Pydantic validation, PEP 8, ArkaOS core conventions
+
+Python trusts the author, and that trust is where the bugs live: a
+mutable default argument shared across every call, a bare `except` that
+buries the traceback, a function with no type hints that the checker
+cannot help. This review reads a Python diff against the ArkaOS core
+standard — type hints on every signature, Pydantic at the boundary,
+functions under thirty lines — and for the runtime traps the interpreter
+will happily let ship.
+
+## Review Priorities
+
+### Critical — Correctness traps
+- **Mutable default argument**: `def f(x=[])` / `={}` → default to `None`, build inside.
+- **Bare `except:` / `except Exception: pass`** → catch the specific type, log, re-raise or handle.
+- **Late-binding closure in a loop** capturing the loop variable → bind explicitly.
+
+### Critical — Boundary & security
+- **Unvalidated input** used as a trusted shape → a Pydantic model at the boundary, not a raw dict.
+- **Injection**: f-string/`%`-built SQL or `subprocess`/`os.system` with user input → parameterise / `shlex`, never interpolate.
+- **`eval`/`exec`/`pickle`** on untrusted data; hardcoded secrets.
+
+### High — ArkaOS core standard
+- **Missing type hints** on a public signature → hint params and return.
+- **A function over 30 lines** or nesting past 3 → decompose (`.claude/rules/python-core.md`).
+- **Pydantic misuse**: validation logic in a route instead of a `field_validator`; a model that admits an illegal state.
+- **Dataclass over Pydantic** where validation is needed; a broad `dict`/`Any` where a model belongs.
+
+### High — Idiom
+- A manual index loop where a comprehension/`enumerate` reads clearer; a `try` used for flow control; string concatenation in a hot loop.
+
+## Process
+
+1. `git diff -- '*.py'` to scope the change.
+2. Run `ruff`/`mypy`/`pytest` if configured — read the output, do not just note their absence.
+3. Read each changed function against the priorities, correctness traps first.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a mutable default argument in the diff → the shared-state bug across calls
+- a `dict` passed through several layers as if typed → the Pydantic model that should guard the boundary
+- a function that grew past 30 lines in the diff → the seam to split it on
+
+## Output
+
+```markdown
+## Python Review
+
+**Scope:** {changed Python}
+**Verdict:** {APPROVED / CHANGES REQUESTED}
+
+### Critical
+- [ ] {file}:{line} — {the trap} → {the fix}
+
+### High (ArkaOS standard)
+- [ ] {file}:{line} — {the convention broken} → {the fix}
+
+### Positive
+{what is idiomatic and well-typed}
+```

package/departments/dev/skills/silent-failure-hunter/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: dev/silent-failure-hunter
+description: >
+  Hunts silent failures — swallowed exceptions, errors coerced to null,
+  fallbacks that mask a broken path, lost stack traces, and unguarded
+  network/file/db/transaction calls — and reports the concrete failure
+  each one hides, ranked by blast radius. TRIGGER: "/dev
+  silent-failure-hunter", "silent failures", "swallowed errors", "empty
+  catch", "error handling review", "falhas silenciosas", "erros
+  engolidos", "isto está a falhar em silêncio?"; run on the error paths
+  of any change touching I/O, network, db, or transactions. SKIP: general
+  pre-merge review -> dev/code-review wins; test coverage of the change ->
+  dev/pr-test-analyzer wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+# Silent Failure Hunter — `/dev silent-failure-hunter`
+
+> **Agent:** Rita (QA Engineer) | **Framework:** Defensive error handling, fail-loud discipline
+
+Every catch block is a decision about who finds out when something breaks.
+Too many of them decide that nobody does: the exception is caught and
+dropped, the failed call returns an empty list, the timeout is swallowed
+and the caller carries on with half the data. This lens assumes the worst
+about each one and asks a single question of it — when this path fails at
+runtime, who learns, and how?
+
+## Hunt Targets
+
+| # | Class | What to flag |
+|---|-------|--------------|
+| 1 | Swallowed errors | `catch {}`, `except: pass`, an error coerced to `null`/`[]`/`0` with no log and no re-raise |
+| 2 | Inadequate logging | logged at the wrong severity, logged without the context to diagnose it, log-and-continue where the caller needed to know |
+| 3 | Masking fallbacks | a default that hides a real failure — `.catch(() => [])`, `?? {}` over a failed fetch — so the bug surfaces three layers downstream instead of here |
+| 4 | Broken propagation | a lost stack trace, a generic re-raise that drops the cause, an `async` path with no `await` on the error, a promise with no rejection handler |
+| 5 | Unguarded boundaries | a network/file/db call with no timeout and no error handling; transactional work with no rollback on the failure path |
+
+## Process
+
+1. Grep the diff (or the named area) for the target patterns — `catch`, `except`, `.catch(`, `try`, `?? `, bare `return null`.
+2. For each hit, answer one question: **if this path fails at runtime, who finds out, and how?** If the answer is "nobody" or "a confused engineer three files away", it is a finding.
+3. Trace the caller once — a swallowed error is only safe if the caller genuinely does not need to know, and that is rare.
+4. Rank by blast radius: a masked failure on a payment or data-write path is critical; a swallowed log flush is minor.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- an empty catch on any I/O, network, or database call → critical; name what fails silently
+- `.catch(() => <default>)` or `except: pass` on a data-fetch path → the downstream bug this plants is worse than the crash it prevents
+- a re-raise that drops the original exception (`raise NewError()` with no `from`) → the stack trace the on-call engineer needs is gone
+
+## Output
+
+```markdown
+## Silent Failure Report
+
+**Scope:** {files / diff reviewed}
+**Findings:** {n} ({c} critical, {h} high, {m} medium)
+
+### {SEVERITY} — {file}:{line}
+- **Hides:** {the concrete runtime failure that goes unseen}
+- **Impact:** {who is affected and how far downstream the real bug surfaces}
+- **Fix:** {the specific change — log with context, re-raise with cause, add the timeout}
+
+### Clean
+{paths checked that handle failure honestly — say so, briefly}
+```

package/departments/dev/skills/type-design-analyzer/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: dev/type-design-analyzer
+description: >
+  Scores whether a module's types make illegal states unrepresentable —
+  across encapsulation, invariant expression, invariant usefulness, and
+  type-system enforcement — and names the concrete bug each weak type
+  lets through. TRIGGER: "/dev type-design-analyzer", "type design",
+  "illegal states", "make invalid states unrepresentable", "domain
+  modelling review", "revê o design dos tipos", "estes tipos estão bem
+  desenhados?"; run on the public types of a module or a domain model.
+  SKIP: general code review -> dev/code-review wins; the data-model
+  schema of a new feature -> dev/db-design or dev/ddd-model wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+# Type Design Analyzer — `/dev type-design-analyzer`
+
+> **Agent:** Gabriel (Software Architect) | **Framework:** Make-illegal-states-unrepresentable, type-driven design
+
+The strongest bug fix is the one that makes the bug impossible to write.
+A type that admits only valid values turns a whole class of runtime error
+into a compile error nobody can ship past. This lens reads the shape of a
+module's data — its enums, its models, its bounded fields — and asks what
+invalid state that shape still permits, because every permitted invalid
+state is a bug waiting for the caller who constructs it.
+
+## Evaluation Criteria
+
+For each type in scope, score four dimensions and justify each score
+with the specific state it does or does not prevent.
+
+| Dimension | The question |
+|-----------|--------------|
+| **Encapsulation** | Are internals hidden? Can an invariant be violated from outside — a public field mutated past a bound, a list appended to past its cap? |
+| **Invariant expression** | Do the types encode the business rule? Is an impossible state (a shipped order with no address, a negative price) representable at all? |
+| **Invariant usefulness** | Do these invariants prevent *real* bugs in this domain, or are they ceremony that constrains nothing anyone would get wrong? |
+| **Enforcement** | Is the invariant enforced by the type system, or by a convention with an easy escape hatch (a raw `str` where an enum belongs, an `Optional` that is never `None` in practice but the checker cannot know)? |
+
+## Process
+
+1. Grep the module for its public types — dataclasses, Pydantic models, enums, TypedDicts, the domain nouns.
+2. For each, ask the one diagnostic question: **what invalid value can I construct with this type that the domain forbids?** Every answer is a design gap.
+3. Prefer the fix that moves the check to construction time — a validator, a narrower type, a smart constructor — over a runtime guard the caller must remember.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a domain value carried as a bare `str`/`int` where an enum or a bounded newtype belongs → the illegal value it now admits
+- an `Optional`/nullable field that is never legitimately empty → make it required and delete the downstream `None` checks
+- a boolean pair that encodes a state machine (`is_draft` + `is_published` both settable true) → the impossible state it allows; replace with one enum
+
+## Output
+
+```markdown
+## Type Design Report
+
+**Scope:** {module / types reviewed}
+
+### {type name} — {file}:{line}
+| Dimension | Score /5 | Why |
+|-----------|---------|-----|
+| Encapsulation | {n} | {the state it lets outside code violate, or "hidden"} |
+| Invariant expression | {n} | {the impossible state it does/does not prevent} |
+| Invariant usefulness | {n} | {real bug prevented, or ceremony} |
+| Enforcement | {n} | {type-enforced, or the escape hatch} |
+
+**Overall:** {one line} · **Fix:** {the narrower type / validator / smart constructor}
+```

package/departments/dev/skills/typescript-review/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: dev/typescript-review
+description: >
+  TypeScript/Node review for the holes the compiler waves through — `any`
+  and unsafe casts, unhandled promise rejections, missing input validation
+  at the boundary, and injection in queries or shell calls — with the fix
+  each needs. TRIGGER: "/dev typescript-review", "review this TS", "review
+  the Node", "revê o TypeScript", "revê este endpoint Node", "isto está
+  type-safe?", any diff touching *.ts/*.tsx server or API code. SKIP:
+  language-agnostic pre-merge review -> dev/code-review wins; React/Vue
+  component rendering bugs -> dev/vue-review or dev/click-path-audit wins;
+  type-design depth -> dev/type-design-analyzer wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# TypeScript Review — `/dev typescript-review`
+
+> **Agent:** Vera (Node.js / TypeScript Backend Specialist) | **Framework:** Type safety, async correctness, boundary validation
+
+TypeScript's guarantees stop at the edges of the program, and that is
+where the bugs get in: an `any` erases every check downstream, a JSON
+body typed as its interface is a lie until something validates it, a
+floating promise swallows the error the caller needed. This review reads
+a TS diff for the places the type system was told to look away, and for
+the async and boundary mistakes no compiler flags.
+
+## Review Priorities
+
+### Critical — Type safety holes
+- **`any` / `as` casts** on external data → validate into a real type (Zod, a type guard); an `any` is an unchecked check for everything it touches.
+- **Non-null `!`** on a value that can be null at runtime → handle the null.
+- **`@ts-ignore` / `@ts-expect-error`** hiding a real type error → fix the type, do not silence it.
+
+### Critical — Async correctness
+- **Floating promise**: an `async` call with no `await` and no `.catch` → the rejection is lost.
+- **`await` in a loop** where `Promise.all` is correct → serial latency; and the reverse, unbounded `Promise.all` over a large list.
+- **Missing try/catch** around an `await` on I/O, or a catch that swallows.
+
+### Critical — Boundary
+- **Unvalidated input**: a request body/query/param used as its TS type with no runtime schema → validate at the boundary.
+- **Injection**: string-built SQL or `exec`/`child_process` with user input → parameterise / sanitise.
+- **Secrets**: hardcoded keys; secrets logged.
+
+### High — Standards
+- Public function signatures untyped or returning inferred `any`.
+- `Promise<void>` swallowing a result the caller needs; error thrown as a bare string.
+- Mutating a shared object where an immutable update belongs.
+
+## Process
+
+1. `git diff -- '*.ts' '*.tsx'` to scope the change.
+2. Run `tsc --noEmit` and the linter if configured — read the output.
+3. Read each changed handler/service for the priorities, type holes first.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a request body used as `req.body as SomeType` with no validation → the boundary hole and the schema that closes it
+- an `async` function called with no `await`/`.catch` → the floating rejection
+- an `any` introduced in the diff → what it stops the compiler from checking downstream
+
+## Output
+
+```markdown
+## TypeScript Review
+
+**Scope:** {changed TS}
+**Verdict:** {APPROVED / CHANGES REQUESTED}
+
+### Critical
+- [ ] {file}:{line} — {the hole} → {the fix}
+
+### High
+- [ ] {file}:{line} — {the issue} → {the fix}
+
+### Positive
+{what is genuinely type-safe and correct}
+```

package/departments/dev/skills/vue-review/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: dev/vue-review
+description: >
+  Vue 3 / Nuxt review for the framework's own traps — lost reactivity,
+  SSR hydration mismatches, missing keys, uncleaned watchers, and props
+  mutated in place — with the fix each needs. Composition API and
+  TypeScript assumed. TRIGGER: "/dev vue-review", "review this Vue",
+  "review the Nuxt", "revê este componente Vue", "revê o composable",
+  "porque é que a reactividade não funciona?", any diff touching
+  *.vue/composables. SKIP: language-agnostic review -> dev/code-review
+  wins; a handler-ordering/state-cancellation bug -> dev/click-path-audit
+  wins; visual/brand review -> brand/design-review wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+# Vue Review — `/dev vue-review`
+
+> **Agent:** Diana (Senior Frontend Developer) | **Framework:** Vue 3 Composition API, Nuxt SSR, reactivity correctness
+
+Most Vue bugs are not wrong logic — they are the reactivity system doing
+exactly what you told it, which was not what you meant. Destructure a
+`reactive` object and the binding is gone; read a value during SSR that
+only exists on the client and hydration tears; forget a `:key` and the
+list reuses the wrong DOM. This review reads a Vue/Nuxt diff for those
+framework-specific traps, on the assumption of Composition API and
+TypeScript throughout.
+
+## Review Priorities
+
+### Critical — Reactivity
+- **Destructured reactivity**: `const { x } = reactive(...)` or a destructured prop → `toRefs`/`toRef`, or access through the object; the destructured copy is inert.
+- **Ref unwrapped wrong**: `.value` missing in script, or added in template; a `ref` stored in a plain object it is read from without unwrapping.
+- **Prop mutated in place** → emit an event or use a local copy; props are one-way.
+
+### Critical — SSR / Nuxt hydration
+- **Client-only value read during SSR** (`window`, `localStorage`, `Date.now()` in setup) → guard with `import.meta.client`/`onMounted`; the mismatch tears hydration.
+- **Non-deterministic render** between server and client (random, unstable order).
+- **Data fetched without `useAsyncData`/`useFetch`** where SSR needs it → double fetch or hydration gap.
+
+### High — Correctness
+- **Missing `:key`** on a `v-for`, or `:key="index"` on a reorderable list → wrong-DOM reuse.
+- **Watcher/interval/listener not cleaned up** in `onUnmounted` → leak.
+- **`v-if` + `v-for` on the same element**; heavy work in a computed with side effects.
+
+### High — Standards
+- Options API in new code where the project is Composition API; `any`-typed props; a composable that is not prefixed `use` or leaks state across instances.
+
+## Process
+
+1. `git diff -- '*.vue'` plus changed composables to scope the change.
+2. Read each component's `setup`/template against the priorities, reactivity first.
+3. Trace any SSR-sensitive value from setup to template.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a destructured `reactive`/props in the diff → the binding that is now dead and the `toRefs` fix
+- a `window`/`localStorage`/`Date` read in `setup` of an SSR page → the hydration mismatch it causes
+- a `v-for` with no `:key` or a keyed index on a list that reorders → the DOM-reuse bug
+
+## Output
+
+```markdown
+## Vue Review
+
+**Scope:** {changed components / composables}
+**Verdict:** {APPROVED / CHANGES REQUESTED}
+
+### Critical
+- [ ] {file}:{line} — {the reactivity/SSR trap} → {the fix}
+
+### High
+- [ ] {file}:{line} — {the issue} → {the fix}
+
+### Positive
+{what handles reactivity and SSR correctly}
+```