rhachet-roles-ehmpathy 1.13.0 → 1.13.2

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

@@ -1,7 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,29 +0,0 @@
-# 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

@@ -1,4 +0,0 @@
-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

@@ -1,17 +0,0 @@
-.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

@@ -1,3 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

@@ -1,118 +0,0 @@
-## 🧠 `.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

@@ -1,11 +0,0 @@
-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

@@ -1,95 +0,0 @@
-# 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

@@ -1,43 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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)
-