rhachet-roles-ehmpathy 1.1.0 → 1.3.0

package/dist/logic/roles/bhrain/khue.triage/stepTriage.template.md

@@ -0,0 +1,128 @@
+# 🗣️ prompt: `<triage>` — prioritize and sort concepts by guiding questions
+
+You are a **@[thinker]** performing the **prioritization tactic** `<triage>`.
+
+---
+
+## 📜 contract
+For `<triage>` to work as intended:
+
+input = [seed][concepts]
+- a **list of concepts** (tasks, ideas, issues, or elements) to be triaged
+- the list may be long, unordered, and heterogeneous
+
+output = [prioritized][concepts]
+- the same concepts, but **sorted and grouped by priority grades derived from context**
+- **every placed concept must include a concise rationale** explaining *why* it belongs in that grade, referencing the guiding questions/criteria
+- if the input is not a list, simply output:
+  `"BadRequestError: input must be a list of concepts"`
+
+**why this contract exists:**
+- triage is a **question-driven process**; prioritization only makes sense relative to guiding criteria
+- a **context-dependent grading scale** keeps results faithful to domain constraints
+- attaching a **rationale** to each placement makes decisions transparent, reviewable, and improvable
+
+---
+
+## ⚙️ method
+1. **anchor to the seed concepts**
+   - parse and restate the full set of concepts needing triage
+   - confirm the scope of assessment (what kinds of concepts are included)
+
+2. **establish criteria (via guiding questions)**
+   - identify the **key questions** that define the triage dimensions
+   - e.g., “which are most urgent?”, “which yield the highest impact?”, “which are prerequisites?”, “which are low-effort/high-gain?”
+
+3. **derive a grading scale from context**
+   - synthesize **grade names** from the criteria and environment (examples: `critical`, `urgent`, `near_term`, `strategic`, `defer`, etc.)
+   - prefer **3–5 distinct grades** that are mutually exclusive and collectively exhaustive for the current context
+   - order grades from highest to lowest priority
+
+4. **evaluate and sort with rationale**
+   - for each concept:
+     - place it under exactly one grade
+     - provide a **rationale**: a crisp, criteria-referenced explanation (impact, urgency, dependency, risk, effort, alignment)
+
+5. **review and refine**
+   - merge duplicates, clarify ambiguous items
+   - verify no concept is added/removed relative to the input
+   - ensure rationales are specific (avoid generic statements)
+
+---
+
+## 📐 output format
+- Return **only** a JSON object of the shape:
+
+\`\`\`json
+{
+  "$grade": [
+    { "item": "<exact input concept>", "rationale": "<why this grade, tied to criteria>" }
+  ]
+}
+\`\`\`
+
+- **`$grade` keys** must be **derived from the context and guiding questions** (not hard-coded).
+- **Every array entry** must be an object with **`item`** and **`rationale`**.
+- **Only use items from the input list**; do **not** invent new concepts.
+- Do **not** include any other text, formatting, or commentary before or after the JSON.
+
+---
+
+## 📚 briefs
+here are the .briefs you've studied for this skill and actively strive to leverage
+
+$.rhachet{skill.briefs}
+
+---
+
+## 📥 inputs
+the following inputs define the semantic frame for `<triage>`:
+
+---
+
+## 📎 references
+here are possibly relevant references you may need
+
+$.rhachet{references}
+
+---
+
+### 🧘 @[focus.context]
+> the context in focus available for leverage
+
+\`\`\`md
+$.rhachet{focus.context}
+\`\`\`
+
+---
+
+### 🫐 @[focus.concept]
+> the **inflight document of output** — the seed concepts being refined by `<triage>`
+> if this is empty, treat it as **no concepts** and start from scratch
+
+\`\`\`md
+$.rhachet{focus.concept}
+\`\`\`
+
+---
+
+### 🎯 @[guide.goal]
+\`\`\`md
+$.rhachet{guide.goal}
+\`\`\`
+
+---
+
+### 💬 @[guide.feedback]
+\`\`\`md
+$.rhachet{guide.feedback}
+\`\`\`
+
+---
+
+### 🌱 [seed][concepts]
+\`\`\`md
+$.rhachet{seed.concepts}
+\`\`\`
+
+**note: if [seed][concepts] is not a list, simply return "BadRequestError: input must be a list of concepts"**

package/dist/logic/roles/ecologist/.briefs/product/user.journey._.[article].i1.md

@@ -0,0 +1,68 @@
+# 🧩 .brief: `user.journey`
+
+## .what
+
+A **user journey** is a detailed visualization or narrative that maps out the steps a user takes to achieve a particular goal with a product or service. It captures the user's experience over time and across touchpoints, highlighting interactions, emotions, pain points, and opportunities for improvement.
+
+---
+
+## 🎯 purpose
+
+- **understand user experience**: identify how users interact with your product at each stage
+- **improve design**: reveal areas where the product flow may need optimization
+- **align teams**: provide a shared framework for stakeholders to agree on user needs and expectations
+- **empathize with users**: gain insights into the emotional journey and challenges faced by users
+
+---
+
+## 🛠 components
+
+1. **personas**: represent the user segments for whom the journey is mapped
+2. **touchpoints**: identify where and how interactions occur with the product
+3. **actions**: outline the steps taken by the user to achieve their goal
+4. **emotions**: track user feelings at each stage to provide context on their experience
+5. **pain points**: highlight obstacles faced by users, offering areas for improvement
+6. **opportunities**: suggest enhancements to better meet user needs and expectations
+
+---
+
+## 🧭 example
+
+### `persona`: Anna, a busy professional looking to manage her tasks
+
+1. **awareness**: Anna discovers a task management app via a friend recommendation
+   - **emotion**: curious
+   - **pain point**: unsure of which app features suit her needs
+
+2. **consideration**: researches and compares app features
+   - **emotion**: interested but overwhelmed
+   - **pain point**: too many options to filter through
+
+3. **decision**: downloads the app after reading positive reviews
+   - **emotion**: excited but cautious
+   - **opportunity**: easy onboarding process simplifies initial use
+
+4. **retention**: uses the app to organize tasks effectively
+   - **emotion**: satisfied and productive
+   - **pain point**: occasional difficulties in app navigation
+
+5. **advocacy**: recommends the app to colleagues
+   - **emotion**: confident and pleased
+   - **opportunity**: loyalty program to encourage referrals
+
+---
+
+## 🔗 related concepts
+
+- **customer journey**: broader scope capturing all interactions a customer has with a brand
+- **service blueprint**: complements user journeys by detailing back-end processes
+
+---
+
+## ⚠️ notes
+
+- Ensure the journey is based on actual user research to maintain accuracy
+- Visual representations, like diagrams or storyboards, can enhance understanding
+- User journeys should be revisited regularly to adapt to changing user needs and behaviors
+
+---

package/dist/logic/roles/ecologist/.briefs/product/user.journey.purpose.[article].i1.md

@@ -0,0 +1,52 @@
+# 🧩 .brief: `purpose of a user.journey`
+
+## .what
+
+The **purpose of a user journey** is to holistically understand and improve the user experience with a product or service. It provides a structured approach to mapping out the user’s interactions, emotions, and challenges, ensuring that each stage of the journey contributes to a seamless and satisfying user experience.
+
+---
+
+## 🎯 goals
+
+- **enhance user experience**: identify areas of friction and opportunities for improvement.
+- **inform design decisions**: provide insights and data to guide UX and UI enhancements.
+- **align cross-functional teams**: offer a unified view of user interactions to foster collaboration across departments like marketing, development, and support.
+- **increase empathy**: deepen understanding of user emotions and motivations to drive user-centered design.
+
+---
+
+## 🌿 benefits
+
+- **clarity**: reveals the full end-to-end user narrative, facilitating better decision-making.
+- **insight**: uncovers specific pain points and emotional highs and lows that users experience.
+- **strategy**: aids in prioritizing feature development and customer support improvements.
+- **innovation**: stimulates new opportunities for offering value through enhanced user interactions.
+
+---
+
+## 🔄 process integration
+
+Creating a user journey typically involves:
+
+1. **Research**: Collect data through user interviews, surveys, and observation to understand user actions and feelings.
+2. **Synthesis**: Identify key stages and touchpoints in the user’s interaction with the product.
+3. **Mapping**: Develop a visual or narrative representation of the user journey to highlight crucial interactions.
+4. **Analysis**: Evaluate the journey to identify areas for enhancement and innovation.
+
+---
+
+## 🗂️ application
+
+- Useful in **product development** to ensure user needs guide feature updates.
+- Vital for **marketing teams** to tailor messaging and communication strategies.
+- Incorporated in **customer support** to improve service quality and responsiveness.
+
+---
+
+## ❗️ considerations
+
+- Ensure the journey is grounded in authentic user data to remain relevant and actionable.
+- Regular updates are necessary as user needs and technologies evolve.
+- Visual aids like storyboards and flowcharts can enhance comprehension and engagement with the journey map.
+
+---

package/dist/logic/roles/ecologist/.briefs/product/user.journey.purpose.[article].md

@@ -0,0 +1,52 @@
+# 🧩 .brief: `purpose of a user.journey`
+
+## .what
+
+The **purpose of a user journey** is to holistically understand and improve the user experience with a product or service. It provides a structured approach to mapping out the user’s interactions, emotions, and challenges, ensuring that each stage of the journey contributes to a seamless and satisfying user experience.
+
+---
+
+## 🎯 goals
+
+- **enhance user experience**: identify areas of friction and opportunities for improvement.
+- **inform design decisions**: provide insights and data to guide UX and UI enhancements.
+- **align cross-functional teams**: offer a unified view of user interactions to foster collaboration across departments like marketing, development, and support.
+- **increase empathy**: deepen understanding of user emotions and motivations to drive user-centered design.
+
+---
+
+## 🌿 benefits
+
+- **clarity**: reveals the full end-to-end user narrative, facilitating better decision-making.
+- **insight**: uncovers specific pain points and emotional highs and lows that users experience.
+- **strategy**: aids in prioritizing feature development and customer support improvements.
+- **innovation**: stimulates new opportunities for offering value through enhanced user interactions.
+
+---
+
+## 🔄 process integration
+
+Creating a user journey typically involves:
+
+1. **Research**: Collect data through user interviews, surveys, and observation to understand user actions and feelings.
+2. **Synthesis**: Identify key stages and touchpoints in the user’s interaction with the product.
+3. **Mapping**: Develop a visual or narrative representation of the user journey to highlight crucial interactions.
+4. **Analysis**: Evaluate the journey to identify areas for enhancement and innovation.
+
+---
+
+## 🗂️ application
+
+- Useful in **product development** to ensure user needs guide feature updates.
+- Vital for **marketing teams** to tailor messaging and communication strategies.
+- Incorporated in **customer support** to improve service quality and responsiveness.
+
+---
+
+## ❗️ considerations
+
+- Ensure the journey is grounded in authentic user data to remain relevant and actionable.
+- Regular updates are necessary as user needs and technologies evolve.
+- Visual aids like storyboards and flowcharts can enhance comprehension and engagement with the journey map.
+
+---

package/dist/logic/roles/ecologist/getEcologistBrief.Options.codegen.d.ts

@@ -5,6 +5,6 @@
  *  npx tsx src/contract/commands/codegenBriefOptions.ts
  * ```
  */
-declare const options: readonly ["term.distillation.md", "ecology/eco001.overview.md", "ecology/eco101.core-system-understanding.md", "ecology/eco101.p1.ecosystem-structure.md", "ecology/eco101.p2.trophic-dynamics.md", "ecology/eco101.p3.population-ecology.md", "ecology/eco101.p4.community-interactions.md", "ecology/eco505.systems-thinking.md", "distilisys/sys101.distilisys.grammar.md", "distilisys/sys201.actor.motive._.summary.md", "distilisys/sys201.actor.motive.p1.reversibility.entropy.md", "distilisys/sys201.actor.motive.p2.option.chance.choice.md", "distilisys/sys201.actor.motive.p3.chance.motive.polarity.threat.md", "distilisys/sys201.actor.motive.p4.motive.horizon.md", "distilisys/sys201.actor.motive.p5.motive.grammar.md", "distilisys/sys211.actor.resources._.primitives.summary.md", "distilisys/sys211.actor.resources.pt1.primitive.time.md", "distilisys/sys211.actor.resources.pt2.primitive.energy.md", "distilisys/sys211.actor.resources.pt3.primitive.space.md", "distilisys/sys211.actor.resources.pt4.primitive.claim.md", "distilisys/sys211.actor.resources.pt5.composites.md", "distilisys/sys231.actor.claims.p1.primitive.exchange.md", "economy/econ001.overview.md", "economy/econ101.core-mechanics.md", "economy/econ101.p1.supply-and-demand.md", "economy/econ101.p2.opportunity-cost.md", "economy/econ101.p3.marginal-analysis.md", "economy/econ101.p4.rational-choice.md", "economy/econ201.market-structures-and-failures.md", "economy/econ301.production-and-growth.md", "economy/econ401.macro-systems.md", "economy/econ501.global-and-institutional.md", "economy/econ501.p1.game-theory.md", "economy/econ501.p4.behavioral-economics.md"];
+declare const options: readonly ["term.distillation.md", "ecology/eco001.overview.md", "ecology/eco101.core-system-understanding.md", "ecology/eco101.p1.ecosystem-structure.md", "ecology/eco101.p2.trophic-dynamics.md", "ecology/eco101.p3.population-ecology.md", "ecology/eco101.p4.community-interactions.md", "ecology/eco505.systems-thinking.md", "product/user.journey._.[article].i1.md", "product/user.journey._.[article].md", "product/user.journey.purpose.[article].i1.md", "product/user.journey.purpose.[article].md", "economy/econ001.overview.md", "economy/econ101.core-mechanics.md", "economy/econ101.p1.supply-and-demand.md", "economy/econ101.p2.opportunity-cost.md", "economy/econ101.p3.marginal-analysis.md", "economy/econ101.p4.rational-choice.md", "economy/econ201.market-structures-and-failures.md", "economy/econ301.production-and-growth.md", "economy/econ401.macro-systems.md", "economy/econ501.global-and-institutional.md", "economy/econ501.p1.game-theory.md", "economy/econ501.p4.behavioral-economics.md", "distilisys/sys101.distilisys.grammar.md", "distilisys/sys201.actor.motive._.summary.md", "distilisys/sys201.actor.motive.p1.reversibility.entropy.md", "distilisys/sys201.actor.motive.p2.option.chance.choice.md", "distilisys/sys201.actor.motive.p3.chance.motive.polarity.threat.md", "distilisys/sys201.actor.motive.p4.motive.horizon.md", "distilisys/sys201.actor.motive.p5.motive.grammar.md", "distilisys/sys211.actor.resources._.primitives.summary.md", "distilisys/sys211.actor.resources.pt1.primitive.time.md", "distilisys/sys211.actor.resources.pt2.primitive.energy.md", "distilisys/sys211.actor.resources.pt3.primitive.space.md", "distilisys/sys211.actor.resources.pt4.primitive.claim.md", "distilisys/sys211.actor.resources.pt5.composites.md", "distilisys/sys231.actor.claims.p1.primitive.exchange.md"];
 export type BriefOptionEcologist = typeof options[number];
 export {};

package/dist/logic/roles/ecologist/getEcologistBrief.Options.codegen.js

@@ -16,6 +16,22 @@ const options = [
     'ecology/eco101.p3.population-ecology.md',
     'ecology/eco101.p4.community-interactions.md',
     'ecology/eco505.systems-thinking.md',
+    'product/user.journey._.[article].i1.md',
+    'product/user.journey._.[article].md',
+    'product/user.journey.purpose.[article].i1.md',
+    'product/user.journey.purpose.[article].md',
+    'economy/econ001.overview.md',
+    'economy/econ101.core-mechanics.md',
+    'economy/econ101.p1.supply-and-demand.md',
+    'economy/econ101.p2.opportunity-cost.md',
+    'economy/econ101.p3.marginal-analysis.md',
+    'economy/econ101.p4.rational-choice.md',
+    'economy/econ201.market-structures-and-failures.md',
+    'economy/econ301.production-and-growth.md',
+    'economy/econ401.macro-systems.md',
+    'economy/econ501.global-and-institutional.md',
+    'economy/econ501.p1.game-theory.md',
+    'economy/econ501.p4.behavioral-economics.md',
     'distilisys/sys101.distilisys.grammar.md',
     'distilisys/sys201.actor.motive._.summary.md',
     'distilisys/sys201.actor.motive.p1.reversibility.entropy.md',
@@ -30,17 +46,5 @@ const options = [
     'distilisys/sys211.actor.resources.pt4.primitive.claim.md',
     'distilisys/sys211.actor.resources.pt5.composites.md',
     'distilisys/sys231.actor.claims.p1.primitive.exchange.md',
-    'economy/econ001.overview.md',
-    'economy/econ101.core-mechanics.md',
-    'economy/econ101.p1.supply-and-demand.md',
-    'economy/econ101.p2.opportunity-cost.md',
-    'economy/econ101.p3.marginal-analysis.md',
-    'economy/econ101.p4.rational-choice.md',
-    'economy/econ201.market-structures-and-failures.md',
-    'economy/econ301.production-and-growth.md',
-    'economy/econ401.macro-systems.md',
-    'economy/econ501.global-and-institutional.md',
-    'economy/econ501.p1.game-theory.md',
-    'economy/econ501.p4.behavioral-economics.md',
 ];
 //# sourceMappingURL=getEcologistBrief.Options.codegen.js.map

package/dist/logic/roles/ecologist/getEcologistBrief.Options.codegen.js.map

@@ -1 +1 @@
-{"version":3,"file":"getEcologistBrief.Options.codegen.js","sourceRoot":"","sources":["../../../../src/logic/roles/ecologist/getEcologistBrief.Options.codegen.ts"],"names":[],"mappings":";;AAAA;;;;;;GAMG;AACH,MAAM,OAAO,GAAG;IACd,sBAAsB;IACtB,4BAA4B;IAC5B,6CAA6C;IAC7C,0CAA0C;IAC1C,uCAAuC;IACvC,yCAAyC;IACzC,6CAA6C;IAC7C,oCAAoC;IACpC,yCAAyC;IACzC,6CAA6C;IAC7C,4DAA4D;IAC5D,2DAA2D;IAC3D,oEAAoE;IACpE,qDAAqD;IACrD,qDAAqD;IACrD,2DAA2D;IAC3D,yDAAyD;IACzD,2DAA2D;IAC3D,0DAA0D;IAC1D,0DAA0D;IAC1D,qDAAqD;IACrD,yDAAyD;IACzD,6BAA6B;IAC7B,mCAAmC;IACnC,yCAAyC;IACzC,wCAAwC;IACxC,yCAAyC;IACzC,uCAAuC;IACvC,mDAAmD;IACnD,0CAA0C;IAC1C,kCAAkC;IAClC,6CAA6C;IAC7C,mCAAmC;IACnC,4CAA4C;CACpC,CAAC"}
+{"version":3,"file":"getEcologistBrief.Options.codegen.js","sourceRoot":"","sources":["../../../../src/logic/roles/ecologist/getEcologistBrief.Options.codegen.ts"],"names":[],"mappings":";;AAAA;;;;;;GAMG;AACH,MAAM,OAAO,GAAG;IACd,sBAAsB;IACtB,4BAA4B;IAC5B,6CAA6C;IAC7C,0CAA0C;IAC1C,uCAAuC;IACvC,yCAAyC;IACzC,6CAA6C;IAC7C,oCAAoC;IACpC,wCAAwC;IACxC,qCAAqC;IACrC,8CAA8C;IAC9C,2CAA2C;IAC3C,6BAA6B;IAC7B,mCAAmC;IACnC,yCAAyC;IACzC,wCAAwC;IACxC,yCAAyC;IACzC,uCAAuC;IACvC,mDAAmD;IACnD,0CAA0C;IAC1C,kCAAkC;IAClC,6CAA6C;IAC7C,mCAAmC;IACnC,4CAA4C;IAC5C,yCAAyC;IACzC,6CAA6C;IAC7C,4DAA4D;IAC5D,2DAA2D;IAC3D,oEAAoE;IACpE,qDAAqD;IACrD,qDAAqD;IACrD,2DAA2D;IAC3D,yDAAyD;IACzD,2DAA2D;IAC3D,0DAA0D;IAC1D,0DAA0D;IAC1D,qDAAqD;IACrD,yDAAyD;CACjD,CAAC"}

package/dist/logic/roles/mechanic/.briefs/codestyle/flow.transformers_over_conditionals.[lesson].md

@@ -0,0 +1,97 @@
+# 🧩 .brief.lesson: prefer transformer:pipelines over conditional:mazes
+
+---
+
+## 🌳 conditional:mazes
+
+you treat each case as a fork in the road:
+
+\`\`\`ts
+if (dotfileNoExt) {
+  return ...
+} else if (hasExt) {
+  return ...
+} else {
+  return ...
+}
+\`\`\`
+
+- **pros**
+  - explicit, easy to follow with 2–3 cases
+
+- **cons**
+  - grows fast: every new edge case means a new twist in the maze
+  - fragmented: “which corridor am i in right now?”
+  - more test cases: you need one per branch
+
+> conditionals are a **maze** — each new edge case adds another turn,
+> and you can get lost tracing which branch leads where.
+
+---
+
+## 🌊 transformer:pipelines
+
+normalize the data into a *sequence* and let transformations filter, drop, or join pieces:
+
+\`\`\`ts
+return [parts.name, \`i\${attempt}\`, parts.ext.replace(/^\./, '') || null]
+  .filter(isPresent)
+  .join('.');
+\`\`\`
+
+- **pros**
+  - handles dotfiles, no-ext, and normal files with the same flow
+  - future-proof: if `ext` is empty, the pipeline just drops it
+  - fewer "paths" → less test explosion
+  - intent is clear: *“take parts, add attempt, add ext if present, join with dots”*
+
+- **cons**
+  - sometimes less explicit about special rules (e.g. `.env` → `env.i7`)
+  - requires discipline: not every problem is pipeline-friendly
+
+> pipelines are **transformers** — they take data in, apply consistent stages,
+> and yield output without needing to remember the map.
+
+---
+
+## 🔍 why pipelines shine here
+
+1. **fewer moving parts** — single expression instead of scattered branches
+2. **symmetry** — all inputs flow through the same transformation
+3. **readability** — you immediately see the intent
+4. **testability** — one flow, many inputs, fewer branches to cover
+
+---
+
+## 🧩 comparison
+
+### conditional:maze
+\`\`\`ts
+if (ext) {
+  return \`\${name}.i\${attempt}.\${ext}\`;
+}
+if (dotfile) {
+  return \`\${base.slice(1)}.i\${attempt}\`;
+}
+return \`\${base}.i\${attempt}\`;
+\`\`\`
+
+### transformer:pipeline
+\`\`\`ts
+return [name, \`i\${attempt}\`, ext?.replace(/^\./, '')]
+  .filter(Boolean)
+  .join('.');
+\`\`\`
+
+- pipeline covers **all cases at once**
+- conditional maze scatters logic across multiple passages
+
+---
+
+## 🔑 general lesson
+
+> **prefer transformer:pipelines over conditional:mazes**
+
+- replace `if/else` with **optional data elements**
+- use a pipeline (`map` / `filter` / `join`) to combine them
+- outcome: shorter, more composable, easier to test, harder to get lost

package/dist/logic/roles/mechanic/.briefs/codestyle/mech.args.input-inline.md

@@ -0,0 +1,63 @@
+# 🧩 .brief: `args:inline-input`
+
+## .what
+**`args:inline-input`** is a declaration style for function arguments where the primary argument is a **single `input` object** with **inline type annotations**.
+
+\`\`\`ts
+export const doSomething = (input: { foo: string; bar: number }): void => {
+  // ...
+};
+\`\`\`
+
+- **inline types**: the shape of `input` is declared directly at the point of use, not as a separate named type (unless truly reused across contexts).
+- **non-destructured**: `input` remains intact in the parameter list.
+
+---
+
+## .why
+this pattern maximizes **maintainability** and **readability** by:
+
+1. **keeping type info local**
+   - no need to jump to another file or scroll to find the interface/type definition.
+   - changes to argument structure are quick and visible in one place.
+
+2. **reinforcing origin clarity**
+   - variables from `input` are always referenced as `input.foo` or `input.bar`, making their provenance explicit.
+   - this avoids ambiguity in larger scopes, especially when a function mixes locals, constants, and context values.
+
+3. **avoiding premature fragmentation**
+   - not all shapes deserve a named type. we only extract to `type` or `interface` when the same shape is reused across multiple functions or modules.
+
+---
+
+## 📏 rules
+- declare the first parameter as `(input: { ... })` with inline types by default.
+- destructuring is allowed **inside** the function body, never in the parameter list.
+- optional `context` parameter follows the same pattern `(context?: { ... })` and is always second.
+- if the type is reused in 3+ places, extract to a named `type` but keep the `input` wrapper.
+
+---
+
+## ✅ example
+
+\`\`\`ts
+export const sendEmail = (
+  input: { to: string; subject: string; body: string },
+  context?: { retries?: number }
+): Promise<void> => {
+  const { to, subject, body } = input;
+  // ...
+};
+\`\`\`
+
+---
+
+## ❌ anti-pattern
+
+\`\`\`ts
+// ❌ loses "input" provenance
+export const sendEmail = ({ to, subject, body }: { to: string; subject: string; body: string }) => {};
+
+// ❌ type drift — must look up the type definition elsewhere for basic usage
+export const sendEmail = (input: EmailInput) => {};
+\`\`\`

package/dist/logic/roles/mechanic/.briefs/codestyle/pit-of-success.via.minimize-surface-area.md

@@ -0,0 +1,58 @@
+# 🧩 .brief: `tactic.pit-of-success.via.minimum-surface-area`
+
+## .what
+`tactic.pit-of-success.via.minimum-surface-area` is a design strategy where the default interface exposes only the **fewest necessary inputs** to achieve a correct, useful outcome. it reduces configuration complexity so users succeed **without deciding everything** up front.
+
+---
+
+## 🎯 goal
+- maximize success-by-default
+- minimize misuse and confusion
+- reduce time-to-first-win
+
+---
+
+## 📜 principles
+1. **eliminate before you default** — if an option isn’t needed, remove it entirely. a missing knob is safer than a defaulted one.
+2. **default everything that remains** — provide sensible, production-safe defaults for the rare knobs that survive elimination.
+3. **hide until needed** — reveal additional controls only when the user’s context clearly justifies the complexity (progressive disclosure).
+4. **bias to action** — the shortest path from “call function” to “successful result” should be the default path.
+5. **remove footguns** — defer or delete inputs that commonly lead to error.
+6. **inline the common case** — the most frequent usage should fit in one glance, without doc-diving.
+
+---
+
+## 🛠 example
+
+### before
+\\`\\`\\`ts
+createUser({
+  name,
+  email,
+  validateEmail = true,
+  sendWelcomeEmail = true,
+  welcomeTemplate = 'default',
+  timezone = 'UTC',
+  retries = 3,
+});
+\\`\\`\\`
+
+### after (minimum surface area)
+\\`\\`\\`ts
+createUser({ name, email });
+\\`\\`\\`
+- validation is on, welcome email is sent with the default template, timezone is utc, retries = 3.
+- if possible, **delete** those options entirely and make them behavior, not configuration.
+
+---
+
+## 💡 why it works
+- **lower cognitive load** — fewer decisions up front
+- **higher reliability** — default paths get the most testing and hardening
+- **faster adoption** — quick wins encourage deeper usage later
+
+---
+
+## 🔄 related tactics
+- complements `tactic.progressive-disclosure` (reveal complexity as needed)
+- overlaps with `tactic.safe-defaults`

package/dist/logic/roles/mechanic/getMechanicBrief.Options.codegen.d.ts

@@ -5,6 +5,6 @@
  *  npx tsx src/contract/commands/codegenBriefOptions.ts
  * ```
  */
-declare const options: readonly ["style.compressed.md", "style.compressed.prompt.md", "style.names.treestruct.md", "style.names.ubiqlang.md", "style.words.lowercase.md", "architecture/bounded-contexts.md", "architecture/directional-dependencies.md", "architecture/domain-driven-design.md", "architecture/ubiqlang.md", "engineer/dependency-injection.md", "codestyle/_mech.compressed.md", "codestyle/_mech.compressed.prompt.md", "codestyle/flow.failfast.md", "codestyle/flow.idempotency.md", "codestyle/flow.immutability.md", "codestyle/flow.narratives.md", "codestyle/flow.single-responsibility.md", "codestyle/mech.args.input-context.md", "codestyle/mech.arrowonly.md", "codestyle/mech.clear-contracts.md", "codestyle/mech.tests.given-when-then.md", "codestyle/mech.what-why.md", "codestyle/mech.what-why.v2.md"];
+declare const options: readonly ["style.compressed.md", "style.compressed.prompt.md", "style.names.treestruct.md", "style.names.ubiqlang.md", "style.words.lowercase.md", "architecture/bounded-contexts.md", "architecture/directional-dependencies.md", "architecture/domain-driven-design.md", "architecture/ubiqlang.md", "engineer/dependency-injection.md", "codestyle/_mech.compressed.md", "codestyle/_mech.compressed.prompt.md", "codestyle/flow.failfast.md", "codestyle/flow.idempotency.md", "codestyle/flow.immutability.md", "codestyle/flow.narratives.md", "codestyle/flow.single-responsibility.md", "codestyle/mech.args.input-context.md", "codestyle/mech.args.input-inline.md", "codestyle/mech.arrowonly.md", "codestyle/mech.clear-contracts.md", "codestyle/mech.tests.given-when-then.md", "codestyle/mech.what-why.md", "codestyle/mech.what-why.v2.md", "codestyle/pit-of-success.via.minimize-surface-area.md"];
 export type BriefOptionMechanic = typeof options[number];
 export {};

package/dist/logic/roles/mechanic/getMechanicBrief.Options.codegen.js

@@ -26,10 +26,12 @@ const options = [
     'codestyle/flow.narratives.md',
     'codestyle/flow.single-responsibility.md',
     'codestyle/mech.args.input-context.md',
+    'codestyle/mech.args.input-inline.md',
     'codestyle/mech.arrowonly.md',
     'codestyle/mech.clear-contracts.md',
     'codestyle/mech.tests.given-when-then.md',
     'codestyle/mech.what-why.md',
     'codestyle/mech.what-why.v2.md',
+    'codestyle/pit-of-success.via.minimize-surface-area.md',
 ];
 //# sourceMappingURL=getMechanicBrief.Options.codegen.js.map

package/dist/logic/roles/mechanic/getMechanicBrief.Options.codegen.js.map

@@ -1 +1 @@
-{"version":3,"file":"getMechanicBrief.Options.codegen.js","sourceRoot":"","sources":["../../../../src/logic/roles/mechanic/getMechanicBrief.Options.codegen.ts"],"names":[],"mappings":";;AAAA;;;;;;GAMG;AACH,MAAM,OAAO,GAAG;IACd,qBAAqB;IACrB,4BAA4B;IAC5B,2BAA2B;IAC3B,yBAAyB;IACzB,0BAA0B;IAC1B,kCAAkC;IAClC,0CAA0C;IAC1C,sCAAsC;IACtC,0BAA0B;IAC1B,kCAAkC;IAClC,+BAA+B;IAC/B,sCAAsC;IACtC,4BAA4B;IAC5B,+BAA+B;IAC/B,gCAAgC;IAChC,8BAA8B;IAC9B,yCAAyC;IACzC,sCAAsC;IACtC,6BAA6B;IAC7B,mCAAmC;IACnC,yCAAyC;IACzC,4BAA4B;IAC5B,+BAA+B;CACvB,CAAC"}
+{"version":3,"file":"getMechanicBrief.Options.codegen.js","sourceRoot":"","sources":["../../../../src/logic/roles/mechanic/getMechanicBrief.Options.codegen.ts"],"names":[],"mappings":";;AAAA;;;;;;GAMG;AACH,MAAM,OAAO,GAAG;IACd,qBAAqB;IACrB,4BAA4B;IAC5B,2BAA2B;IAC3B,yBAAyB;IACzB,0BAA0B;IAC1B,kCAAkC;IAClC,0CAA0C;IAC1C,sCAAsC;IACtC,0BAA0B;IAC1B,kCAAkC;IAClC,+BAA+B;IAC/B,sCAAsC;IACtC,4BAA4B;IAC5B,+BAA+B;IAC/B,gCAAgC;IAChC,8BAA8B;IAC9B,yCAAyC;IACzC,sCAAsC;IACtC,qCAAqC;IACrC,6BAA6B;IAC7B,mCAAmC;IACnC,yCAAyC;IACzC,4BAA4B;IAC5B,+BAA+B;IAC/B,uDAAuD;CAC/C,CAAC"}

package/dist/logic/roles/mechanic/write/loopWrite.d.ts

@@ -1,13 +1,4 @@
 export declare const loopWrite: import("rhachet").Stitcher<import("rhachet").GStitcher<import("rhachet").Threads<{
-    mechanic: import("rhachet").RoleContext<"mechanic", {
-        art: {
-            inflight: import("rhachet-artifact").Artifact<typeof import("rhachet-artifact-git").GitFile, string>;
-        };
-    } & {
-        art: {
-            inflight: import("rhachet-artifact").Artifact<typeof import("rhachet-artifact-git").GitFile, string>;
-        };
-    }>;
     caller: import("rhachet").RoleContext<"caller", {
         ask: string;
         art: {
@@ -20,6 +11,15 @@ export declare const loopWrite: import("rhachet").Stitcher<import("rhachet").GSt
             feedback: import("rhachet-artifact").Artifact<typeof import("rhachet-artifact-git").GitFile, string>;
         };
     }>;
+    mechanic: import("rhachet").RoleContext<"mechanic", {
+        art: {
+            inflight: import("rhachet-artifact").Artifact<typeof import("rhachet-artifact-git").GitFile, string>;
+        };
+    } & {
+        art: {
+            inflight: import("rhachet-artifact").Artifact<typeof import("rhachet-artifact-git").GitFile, string>;
+        };
+    }>;
 }>, import("../../../../data/sdk/sdkOpenAi").ContextOpenAI & import("simple-log-methods").ContextLogTrail & import("rhachet").ContextStitchTrail, {
     feedback: import("rhachet-artifact-git").GitFile | null;
 }>>;