rhachet-roles-ehmpathy 1.13.2 → 1.13.3

package/dist/logic/roles/mechanic/.briefs/criteria.practices/never.term.script.md

@@ -0,0 +1,7 @@
+never use the term `script`
+
+it's overloaded
+
+choose what exactly its purpose is
+
+- adhoc usage? => `command`

package/dist/logic/roles/mechanic/.briefs/criteria.practices/prefer.emojis.chill_nature.md

@@ -0,0 +1,24 @@
+prefer the inclusion of emojis in comments and logs, to make things easier to grok
+
+prefer chill, nature based emojis, to give a zen vibe
+
+---
+
+careful not to do emojis - and try and reuse emojis based on similarities
+
+ideally, no more than 5-7 different emojis would be present at a time, and typically, only for imporant callouts
+
+---
+
+otherwise, use neutral and chill unicode characters for bulletpoints and etc
+
+
+---
+
+e.g.,
+
+⛈️ = error
+🔭 = lookup
+✨ = success
+🌿 = output
+🌊 = outcome

package/dist/logic/roles/mechanic/.briefs/criteria.practices/prefer.jq.over_alt.[demo].md

@@ -0,0 +1,29 @@
+# given
+
+you are in a .shell env
+
+# what
+
+prefer `jq` over escape to other languages, like python
+
+# demo
+
+### bad practice
+
+```sh
+  local instance_id
+  instance_id=$(echo "$instance_json" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+if data and data != 'None':
+  print(data.get('InstanceId', ''))
+" 2>/dev/null)
+```
+
+
+### best practice
+
+```sh
+  local instance_id
+  instance_id=$(echo "$instance_json" | jq -r '.InstanceId // empty' 2>/dev/null)
+```

package/dist/logic/roles/mechanic/.briefs/criteria.practices/prefer.terraform.[criteria].md

@@ -0,0 +1,4 @@
+given('a command which modifies infrastructure')
+  when('it does not leverage terraform')
+    then('flag it as a BLOCKER')
+      sothat('we manage all infrastructure via terraform')

package/dist/logic/roles/mechanic/.briefs/criteria.practices/prefer.terraform.[seed].md

@@ -0,0 +1,17 @@
+.what = use terraform rather than adhoc .shell commands to manage infra
+
+.why =
+  - terraform is declarative
+    - enables you to declare desires and compare reality
+    - simpler to review for issues, since you see the final product explicitly in code
+    - simpler to review for issues, since you see divergence with reality
+    - enables drift detection
+    - more
+
+---
+
+if your goal is to change infra (add resources, del resources, set resources) => use terraform
+
+---
+
+note = code.actors make it very easy to sync terraform state && go from wish => critera => done

package/dist/logic/roles/mechanic/.briefs/criteria.practices/require.dependency.pinned_versions.md

@@ -0,0 +1,3 @@
+always pin versions of dependencies to exact versions
+
+this eliminates surprise changes when our dependencies dont respect semver notation and have an surprise backwards-incompat change

package/dist/logic/roles/mechanic/.briefs/criteria.practices/require.idempotency.md

@@ -0,0 +1,33 @@
+idempotency is a must
+
+we must always assume that retries will occur
+- user will forget if they ran it or not
+- code will compose dependent flows that may need to repeat operations safely
+- apps will face network errors and retry requests
+
+idempotency means that the same request duplicated will succeed as if it only ran once
+
+---
+
+the main methods of doing so are via
+
+- findsert = find or insert
+  - const before = dao.findByRef()
+  - if (before && nonDiff) return before
+  - if (before && hasDiff) BadRequestError.throw('can not findsert; entity already exists but with different attributes')
+  - const after = dao.upsert()
+  - return after
+
+- upsert = update or insert
+  - this is a standard operation often handled at the database layer
+  - simply always overwrite, idempotently
+
+---
+
+why are these the two main modes?
+
+because otherwise the only other option is to throw an error on duplicate requests
+
+there are fundamentally no other ways to support idempotency
+- if it doesn't exist, great -> insert
+- if it does exist, decide -> update (upsert) or retain (findsert)

package/dist/logic/roles/mechanic/.briefs/criteria.practices/require.knowledge.externalized.md

@@ -0,0 +1,17 @@
+if using a tool dependency that is not already fully understood with internalized knowledge
+
+first, it is mandatory to externalize knowledge about that tool
+
+for example
+- what is it
+- when was it released
+- how much does it cost
+- how to use it
+
+- what are advantages and devantages? boons and banes?
+
+---
+
+research this always via a websearch first
+
+and always cite your sources

package/dist/logic/roles/mechanic/.briefs/engineer/dependency-injection.md

@@ -0,0 +1,118 @@
+## 🧠 `.brief.designer.dependency-injection`
+
+### 🧠 topic: dependency injection
+**why we pass in dependencies instead of hardcoding them**
+
+---
+
+### 🎯 goal
+build software that is **flexible, testable, and decoupled**,
+by making dependencies **explicit, swappable, and controlled from the outside**.
+
+---
+
+### 🛠 what it is
+
+> **dependency injection** = giving a function, class, or module what it needs from the outside,
+> rather than letting it construct or look up those tools internally.
+
+for example, instead of having a function reach for its own dependencies:
+
+```ts
+// ❌ tightly coupled and side-effect prone
+import { log } from '@/utils/logger';
+import { getDatabaseConnection } from '@/utils/database';
+
+export const upsert = async ({ cost }: { cost: JobLeadCost }) => {
+  log.debug('began.upsert', { cost });
+  const dbConnection = await getDatabaseConnection();
+  const result = await dbConnection.query('SELECT * FROM ...');
+}
+```
+
+you inject those dependencies via the standard `(input, context)` pattern:
+
+```ts
+// ✅ dependency injection via context
+export const upsert = async (
+  { cost }: { cost: JobLeadCost },
+  context: { dbConnection: DatabaseConnection, log: LogMethods }, // note how the .context pattern cleanly separates inputs from dependencies
+) => {
+  context.log.debug("began.upsert", { cost });
+  const updated = await context.dbConnection.query('SELECT * FROM ...');
+  await emitJobLeadCostSetEvent(result, context); // note how easy it is to reuse dependencies via the context pattern
+  return updated;
+};
+```
+
+- the function doesn’t reach into globals or construct its own tools
+- everything it needs is **passed in from the outside**, making it testable, predictable, and side-effect free
+
+---
+
+### 🔑 paved pattern: `(input, context)`
+dependency injection is best done by following the **standard procedure contract**:
+
+```ts
+export const doThing = async (
+  input: SomeInput,
+  context: { db: Db; log: Logger } & OtherContext
+) => { ... }
+```
+
+- all dependencies go in the `context` argument
+- keeps `input` clean, and `context` flexible
+- enables composition, tracing, and full test control
+
+
+---
+
+### 🤝 why it matters
+
+- **testability** — swap real dependencies with mocks/fakes
+- **flexibility** — easily change implementations without changing core logic
+- **separation of concerns** — business logic doesn't manage its own plumbing
+- **explicitness** — makes system wiring visible and intentional
+- **reusability** — same logic can be reused with different behaviors
+
+---
+
+### 🧱 core principle
+
+> **don’t make decisions deep inside the system.**
+> instead, **let the outer layers decide what gets injected**.
+
+you keep **policies and tools separate from behaviors**.
+
+---
+
+### 🔍 mental model
+
+> dependency injection is like **plugging in a tool** instead of **building one every time**.
+
+your procedures say:
+> “give me what I need — I don’t care where it came from.”
+
+---
+
+### 🔄 practical benefits
+
+| without DI                             | with DI                                    |
+|----------------------------------------|--------------------------------------------|
+| hardcoded database inside procedures   | database passed in as via parameters       |
+| requires real API in tests             | can inject mock/fake API for testing       |
+| logic tied to concrete tools           | logic works with any compatible tool       |
+| hard to switch infra/tools             | swappable with config or environment setup |
+
+---
+
+### 🧩 final synthesis
+
+we inject dependencies to build systems that are easier to **test**, **scale**, and **evolve**.
+
+> dependency injection is about building **pure, decoupled, and testable** systems.
+> it eliminates shared state, surfaces side effects, and makes your logic portable and composable.
+> it enables **modularity**, **testability**, and **control**,
+> by making **dependencies external** instead of hidden inside.
+
+done right, it's **invisible during use**, and **invaluable during testing, scaling, and evolution**.

package/dist/logic/roles/mechanic/.briefs/engineer/dependency-injection.stub.md

@@ -0,0 +1,11 @@
+todo: declare why dependency injection leads to a pit of success && why global shared state should be avoided
+
+via dependency injection, you always know what's referncing what. no side effects
+
+persistance is the only global shared state that should exist - and even that should be managed cautiously (e.g., to avoid race conditions)
+
+---
+
+via dependency injection, either via context or input params, you craft safer, easier to test, and more reliable code
+
+a significant contributor to the pit-of-success we strive for

package/dist/logic/roles/mechanic/.briefs/lessons/code.prod.typescript.types/bivariance_vs_contravariance.[lesson].md

@@ -0,0 +1,95 @@
+# method syntax for bivariance
+
+## .what
+
+typescript treats arrow function properties and method syntax differently for variance:
+
+- **arrow function syntax** = contravariant on parameters
+- **method syntax** = bivariant on parameters
+
+```ts
+// arrow function syntax (contravariant)
+interface Dao {
+  get: (input: SomeInput) => Promise<Result>;
+}
+
+// method syntax (bivariant)
+interface Dao {
+  get(input: SomeInput): Promise<Result>;
+}
+```
+
+---
+
+## .why this matters
+
+when checking if a specific type is assignable to a generic type (e.g., `Dao<Specific>` to `Dao<any>`), contravariance on function parameters can cause unexpected failures.
+
+### example: the problem
+
+```ts
+interface DeclastructDao<TResourceClass> {
+  get: {
+    // arrow syntax = contravariant
+    byPrimary?: (input: RefByPrimary<TResourceClass>) => Promise<Resource | null>;
+  };
+}
+
+// specific dao where RefByPrimary resolves to {uuid: string}
+const specificDao: DeclastructDao<typeof MyResource> = { ... };
+
+// generic dao shape where RefByPrimary<any> resolves to {}
+type GenericDao = DeclastructDao<any>;
+
+// ❌ fails: {uuid: string} is not assignable to {}
+const generic: GenericDao = specificDao;
+```
+
+the contravariant check asks: "can a function accepting `{uuid: string}` be used where a function accepting `{}` is expected?"
+
+answer: **no** — a function requiring `uuid` can't safely accept an empty object.
+
+### example: the fix
+
+```ts
+interface DeclastructDao<TResourceClass> {
+  get: {
+    // method syntax = bivariant
+    byPrimary?(input: RefByPrimary<TResourceClass>): Promise<Resource | null>;
+  };
+}
+
+// ✅ works: bivariance allows assignment in either direction
+const generic: GenericDao = specificDao;
+```
+
+---
+
+## .when to use
+
+use method syntax when:
+
+1. you need interfaces with generic type parameters to be assignable to their `<any>` variants
+2. you're defining dao/repository patterns where specific implementations must fit into generic collections
+3. the interface will be used in `Record<string, Interface<any>>` shapes
+
+---
+
+## .tradeoff
+
+bivariance is slightly less type-safe at the boundary — typescript won't catch certain mismatches. however, this is often the correct behavior for:
+
+- generic collections of typed implementations
+- plugin/provider patterns
+- dao registries
+
+the types remain fully enforced when actually calling the methods on a specific instance.
+
+---
+
+## .reference
+
+this is intentional typescript behavior. method syntax preserves the historical bivariant behavior from before `--strictFunctionTypes` was introduced, because it matches how most developers expect object subtyping to work.
+
+- [typescript handbook: type compatibility](https://www.typescriptlang.org/docs/handbook/type-compatibility.html)
+- [typescript pr: strict function types](https://github.com/microsoft/TypeScript/pull/18654)

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.contract.inputs.nameargs/bad-practice/forbid.positional-args.md

@@ -0,0 +1,43 @@
+positional args are
+- hard to read
+- easy to break
+
+never use positional args if we can avoid them
+
+
+even in bash!
+
+
+---
+
+e.g., which one's easier to understand?
+
+
+```sh
+  # final attempt with fail_on_error=true (exits on hard failures, warns on timeout)
+  _try_start_port_forwarding "$instance_id" "$rds_endpoint" 60 true
+```
+
+
+vs
+
+```sh
+
+  # final attempt with fail_on_error=true (exits on hard failures, warns on timeout)
+  _try_start_port_forwarding \
+    instance_id="$instance_id" \
+    rds_endpoint="$rds_endpoint" \
+    timeout=60 \
+    fail_on_error=true
+```
+
+
+---
+
+
+
+  - Self-documenting: You can see what each parameter is at the call site
+  - Order-independent: Arguments can be passed in any order
+  - Easier to maintain: Adding new optional parameters won't break existing calls
+  - Validation: Each function validates required parameters
+  - Usage examples: Included in function headers

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.contract.inputs.nameargs/best-practice/require.namedargs.md

@@ -0,0 +1,6 @@
+always used named arguments on inputs
+
+they make it clear when reading what the arguments are used for
+
+they also make it possible to reorder arguments without breaking the contract (great for refactors, deprecations, renames, etc)
+