arkaos 4.17.0 → 4.18.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: ecc-derived
+  source: https://github.com/affaan-m/ecc
+  license: MIT
+---
+
+# 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
+
+A "New Email" button called `setComposeMode(true)` then `selectThread(null)`.
+Each call was correct on its own, but `selectThread` reset `composeMode`
+back to false as a side effect, so the button opened nothing — no type
+error, no crash, and no unit test to catch it. Tracing the two calls in
+order makes the reset obvious on the page.
+
+## 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/pr-test-analyzer/SKILL.md

@@ -0,0 +1,79 @@
+---
+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: ecc-derived
+  source: https://github.com/affaan-m/ecc
+  license: MIT
+---
+
+# 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/silent-failure-hunter/SKILL.md

@@ -0,0 +1,72 @@
+---
+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: ecc-derived
+  source: https://github.com/affaan-m/ecc
+  license: MIT
+---
+
+# 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,73 @@
+---
+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: ecc-derived
+  source: https://github.com/affaan-m/ecc
+  license: MIT
+---
+
+# 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}
+```