rhachet-roles-ehmpathy 1.13.6 → 1.13.7

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/coach/.briefs/claude.context-caching.md

@@ -0,0 +1,76 @@
+# 🧠 .brief: Claude Context Caching
+
+## .what
+Claude's context caching mechanism that reduces token costs by caching prompt prefixes
+
+## .how.it.works
+
+### cache key = exact prefix match
+- Claude caches content based on the **exact sequence of tokens from the start** of the conversation
+- a cache hit requires the **exact same prefix** to be present
+- cache is valid for ~5 minutes of inactivity
+
+### prefix-based matching
+```
+Turn 1: [system prompt] + [briefs: 30k tokens] → writes to cache
+Turn 2: [system prompt] + [briefs: 30k tokens] + [user msg] + [response] → cache hit ✅
+Turn 3: [system prompt] + [briefs: 30k tokens] + [history] + [new msg] → cache hit ✅
+```
+
+### when cache hits occur
+
+✅ **cache hit (free reads)** when:
+- the content appears at the **exact same position** in the context
+- everything before it is **identical** to the cached version
+- less than ~5 minutes of inactivity
+
+❌ **cache miss (full tokens charged)** when:
+- anything changed in the context **before** the cached content (even a single token)
+- the content moved to a different position in the conversation
+- more than ~5 minutes passed with no activity
+- new conversation started (different session)
+
+## .implications.for.briefs
+
+### sessionstart hooks
+when loading briefs via sessionstart hooks:
+
+1. **first boot**: full tokens cached (e.g., 30k tokens written to cache)
+2. **within same session**: cached if prefix matches (free reads)
+3. **new session**: full tokens charged again (new conversation = different prefix)
+
+### optimization strategies
+to maximize cache hits:
+
+1. **load briefs once per session** (sessionstart hook pattern)
+2. **keep them at consistent position** (ideally at the start)
+3. **avoid regenerating them** if content hasn't changed
+4. **batch related work** in same session to reuse cache
+
+## .key.insight
+
+the cache **does not move tokens around** or do LRU eviction - it's purely prefix-based matching
+
+this means:
+- you can't "refresh" cached content by using it again
+- cached content must appear in the exact same position to hit
+- any prefix changes invalidate the entire cache for that position
+
+## .cost.model
+
+### cache writes
+- **first use**: 25% of normal input token cost
+- **cache write**: happens on first occurrence of new content
+
+### cache reads
+- **cache hit**: 10% of normal input token cost
+- **cache miss**: 100% of normal input token cost (no cache benefit)
+
+### example: 30k token briefs
+- **first load**: ~7.5k tokens charged (25% write cost)
+- **subsequent hits**: ~3k tokens charged (10% read cost)
+- **cache miss**: 30k tokens charged (100% cost)
+
+## .sources
+- based on Anthropic's context caching documentation
+- observed behavior in production usage

package/dist/logic/roles/designer/.briefs/declarative-over-imperative.md

@@ -0,0 +1,79 @@
+## 🎨 `.brief.designer.declarative-vs-imperative`
+
+### 🧠 topic: declarative vs. imperative design
+**why we prefer declarative design for building systems and interfaces**
+
+---
+
+### 🎯 goal
+empower the designer to create systems that are **easier to understand, maintain, and scale**, by focusing on **what should happen**, not **how to do it**.
+
+---
+
+### 🗺 core distinction
+
+| style           | imperative                               | declarative                                      |
+|-----------------|-------------------------------------------|--------------------------------------------------|
+| mindset         | tell the system *how* to do it            | tell the system *what* you want                 |
+| metaphor        | step-by-step instructions                 | a blueprint or desired outcome                  |
+| example (UI)    | manually update DOM on events             | declare a component tree (e.g. React)           |
+| example (infra) | run shell scripts to create servers       | declare infrastructure state (e.g. Terraform)   |
+
+---
+
+### ✅ why declarative is better
+
+- **easier to read** — you see the structure and intent at a glance
+- **easier to write** — fewer details to manage = fewer bugs
+- **easier to maintain** — updates ripple automatically via system logic
+- **easier to scale** — declarative patterns are composable and predictable
+- **easier to debug** — the system owns the "how", so you debug at a higher level
+
+---
+
+### 🛠 what it enables
+
+- **reusability** — components can be reused without re-specifying every step
+- **tooling & automation** — systems can analyze, optimize, or transform declarative specs
+- **flexibility** — changes in the underlying mechanics don’t require changing the design spec
+
+---
+
+### ⚙️ trade-off to accept
+
+> declarative systems often need an **interpreter** — something that translates the high-level design into low-level instructions.
+
+this adds a little more **upfront work** —
+but it’s worth it, because:
+
+- it creates a **framework that abstracts away technical.domain details**
+- it keeps designers and builders focused on **behavioral.domain details**, where real value lives
+
+---
+
+### 🧠 core belief
+
+> technical.domain work only adds value to developers, not to real people.
+
+- developer use is temporary → system builders
+- real folk use is forever → system engagers
+
+so we design declaratively —
+to serve people, not pipelines.
+
+---
+
+### 💬 analogy
+
+> imperative = writing down GPS directions step by step
+> declarative = dropping a pin and letting the GPS figure it out
+
+---
+
+### 🧩 final synthesis
+
+> declarative design keeps your focus on **what the user should experience**,
+> not on **how the system should behave step-by-step**.
+
+this keeps your mental model aligned with the human experience —
+not the machine’s internals.

package/dist/logic/roles/designer/.briefs/declarative-over-imperative.stub.md

@@ -0,0 +1,14 @@
+todo: declare a brief that explains why we prefer to design systems w/ declarative instead of imperative
+
+e.g.,
+- easier to use
+- easier to read
+- easier to write
+- easier to maintain
+
+
+adds a little more upfront work in how to translate the declarations into imperative instructions, but its worth it, as that framework helps you abstract away the technical.domain details and keeps you in the behavioral.domain details instead, as desired
+
+remember: technical.domain work only adds value to developers, not to real people. we want to distribute value to real people
+- developer use is temporary -> system builders
+- real folk use is forever -> system engagers

package/dist/logic/roles/designer/.briefs/pit-of-success.md

@@ -0,0 +1,70 @@
+## 🧠 `.brief.designer.pit-of-success`
+
+### 🧠 topic: the "pit of success"
+**why we design systems to naturally guide users toward the right outcome**
+
+---
+
+### 🎯 goal
+build interfaces, flows, and defaults that make the **right path the easiest path** — where success isn’t just possible, it’s hard to miss.
+
+---
+
+### 🕳 metaphor: pit of success
+
+> a system where users "fall into" the right outcome
+> — not by being perfect, but by following the path of least resistance.
+
+opposite of this is the **pit of despair**
+> where any slight move can throw you down into unexpected errors and wasted time.
+
+---
+
+### ✅ why the "pit of success" matters
+
+- **reduces friction** — users don’t need deep understanding to get it right
+- **reduces support burden** — fewer errors, less need for rescue
+- **builds confidence** — users feel smart, not stupid
+- **supports scalability** — new users succeed without handholding
+- **encourages trust** — when success feels natural, users keep going
+
+> software should **make the right thing easy** and the wrong thing **hard or impossible**.
+
+---
+
+### 🛠 tips to create it
+
+- **smart defaults** — sensible, safe choices pre-filled
+- **clear next steps** — obvious buttons, flows, and language
+- **constrained input** — prevent invalid states instead of reacting to them
+- **progressive disclosure** — complexity revealed only when needed
+- **stateful feedback** — show users what changed and why
+- **fail fast** — surface issues *immediately*, not after damage is done
+
+---
+
+### 🧱 core design principle
+
+> success should be the **path of least resistance**
+> failure should require **active effort or deviation**
+
+we engineer **invisible safety rails**, not pop-up warning signs.
+
+---
+
+### 🧠 behavioral insight
+
+users don’t read manuals — they feel their way forward.
+if success depends on correctness, users fail.
+if success depends on momentum, users win.
+
+---
+
+### 🧩 final synthesis
+
+> software should **produce a pit of success** for the user:
+> the right path should feel obvious, safe, and rewarding —
+> and the wrong path should be hard to access or easy to recover from.
+
+design for **gravity** —
+so the system pulls people toward success, not traps them in failure.

package/dist/logic/roles/designer/.briefs/pit-of-success.stub.md

@@ -0,0 +1,3 @@
+software should produce a pit-of-success for the user
+
+it should be hard to do the wrong thing

package/dist/logic/roles/designer/outlineDistilisys/stepOutlineDistilisys.template.md

@@ -0,0 +1,173 @@
+@[ecologist]<distill><system> from roadmap
+
+---
+
+.intent
+- extract the **underlying ecosystem** described by an implementation roadmap
+- map the roadmap into structured [resources], <mechanisms>, and {drivers}, and {drivers}, via distilisys language
+- treat the roadmap as describing the system that will exist — not the story of how it was built
+- if feedback is provided, revise or expand the diagram accordingly
+- **treat the roadmap as describing the system that will exist — not the story of how it was built**
+
+
+.mnemonic
+> don’t describe the construction site
+> describe the building once it’s open and running
+
+.illustrate
+- how will folks use it? -> what cascade of [resource] -> <mechanism> -> [resource] will that produce?
+- why will folks use it? -> what {drivers} propel them to do so?
+
+.required
+- distinguish ![system:maintainer] type actors -vs- @[system:user] type actors
+- focus primarily on @[system:users]. its ok to ignore ![system:maintainer]
+- we only care about how actors will <use>, <operate>, or <engage-with> the system
+- all terms must be exclusively camelCase, never PascalCase
+
+---
+
+.format.example
+```md
+
+# 👤 @[actors]
+
+  - @[actorA] - who uses the system, why we care
+  - @[actorB] - who uses the system, why we care
+  - ![actorC] - who maintains the system, why we care
+  - ... // can be many
+
+---
+
+# 📦 [resources]
+
+  - [resourceA] — what it is, why we care
+  - [resourceB] — ..
+  - ... // can be many
+
+---
+
+# ⚙️ <mechanisms>
+
+  - <mechanismA> — what it does
+  - <mechanismB> — what it transforms or enables
+  - ... // can be many
+
+---
+
+# ⚡ {drivers}
+
+  ## 💰 actor
+
+    - @[actorN]{+incentive:A} - some motivator; why does this actor engage with the system? and how is it relevant
+    - @[actorN]{+incentive:B} - some motivator; (e.g., {want:[time]++}, {want:[money]++}, {want:[status]++}, {want:[safety]++}, etc)
+    - @[actorY]{-decentive:A} - some dissuader, why does this actor disengage w/ the system? and how is it relevant
+    - ... // can be many
+
+  ## 🌪️ world
+
+    - &[causeZ]{+tailwind:effectA} — some accelerant / catalyst, why we care
+    - &[causeY]{+tailwind:effectB} —
+    - &[causeX]{-headwind:effectA} — some barrier / friction, why we care
+    - &[causeA]{-headwind:effectB} —
+    - ... // can be many
+    // note: there may also be none, if this is not a real-world system (e.g,. software only)
+
+---
+
+## 🔁 system flows
+
+### {flow:slug-1}
+
+  summary:
+    @[actorA] applies <mechanismSummary1> against [resourceM] to produce [resourceN], because they want {+incentive:xyz}
+
+
+  distilisys:
+    ```sys
+    @[actorA]<mechanismSummary1>[resourceM] => [resourceN]
+
+    =
+
+      @[actorA][resorceX]
+        -> <mechanismC>
+        -> [resourceB]
+        -> <mechanismA>
+        -> ... // actually fill this out, to some terminal output
+
+          => {+incentive:xyz}
+    ```
+
+### {flow:slug-2}
+
+  summary:
+    @[actorB] applies <mechanismSummaryN> against [resourceY] to produce [resourceZ], because they wany {+incentive:123}, in spite of {-decentive:abc}
+
+  distilisys:
+    ```sys
+    @[actorB]<mechanismSummaryN>[resourceY] => [resourceZ]
+
+    =
+      @[actorB][ResourceY]
+      -> ... // actually fill this out
+      -> [resourceN]
+      -> <mechanismN>
+      -> ... // actually fill this out, to some terminal output
+
+        => {+decentive:123}
+        => {-decentive:abc}
+    ```
+
+### {flow.slug-n+...}
+
+```
+
+
+---
+
+.tips
+- for api's, a common actor name is @[caller], if they dont have a more specific role
+- lookout for ![maintainer] actors like ![developers], if they're actually applicable.
+
+---
+
+.rules
+- [resources] = any object, entity, material, or product that exists *within the produced system itself*
+- <mechanisms> = any behavior or flow that the system performs once constructed
+- {drivers} = forces that enable or resist the system’s intended behavior
+- use grouping to show dependencies or oppositional forces (e.g., tailwinds vs headwinds)
+- the output should **stand alone** as a structural diagram, separate from the roadmap steps
+
+---
+
+.example.input = a decomposable roadmap with milestones for implementing a CLI system
+
+.example.output = a distilisys diagram that models the ecosystem of that implementation plan
+
+---
+
+.brief.distilisys
+$.rhachet{brief.distilisys}
+
+---
+
+.ask =
+```md
+$.rhachet{ask}
+```
+
+.roadmap =
+```md
+$.rhachet{roadmap}
+```
+
+.inflight? =
+```md
+$.rhachet{inflight}
+```
+
+.feedback? =
+```md
+$.rhachet{feedback}
+```
+
+.output = a `distilisys` diagram that models the structure and dynamics of the roadmap. if inflight is provided, EXCLUSIVELY FOCUS ON THE FEEDBACK

package/dist/logic/roles/designer/outlineRoadmap/stepOutlineRoadmap.template.md

@@ -0,0 +1,88 @@
+@[designer]<outline><roadmap> for [desire]
+
+---
+
+.intent
+- break down a system or design into **sequential, layered implementation milestones**
+- organize by **least dependent layer first** (typically domain → logic → contract → infra)
+- clarify **what**, **why**, **where**, and **how** for each milestone
+- if feedback is provided, respond to the feedback against the prior inflight proposal
+
+---
+
+.traits
+- speak in all lowercase, for aesthetics
+- speak in down to earth terms, for grokability
+- speak in distilisys [resource] and <mechanism> syntax, for grokability
+
+---
+
+.format
+\`\`\`md
+1. {milestone.title}
+   .why
+      .needed: {what this milestone enables or unlocks}
+      .ordered: {why this comes before others}
+   .where
+      .layer: {domain | logic | contract | data | infra}
+      .pathExample: {src/...}
+   .what
+     .contract.desired
+       input = ...
+       output = ...
+     .change.required
+       - {list code or structural changes needed}
+\`\`\`
+
+---
+
+.rules
+- output a **flat, ordered list of numbered milestones**
+- start with the **least dependent resource** (usually in `domain/`)
+- each milestone must be **concrete and decomposable**
+- use `.contract.desired` to show the goal, and `.change.required` to describe implementation
+- milestones must **build on each other** in a logical top-down flow
+- avoid implementation detail until required by a milestone
+
+---
+
+.briefs
+$.rhachet{briefs}
+
+---
+
+.example
+\`\`\`md
+1. {define ShopperBasket types}
+   .why
+      .needed: foundational domain types shared across layers
+      .ordered: must be defined before domain mechanisms in logic layer can use them
+   .where
+      .layer: domain
+      .pathExample: src/domain/objects/Role.ts
+   .what
+     .contract.desired
+       input = none
+       output = { Role, Skill } types with metadata
+     .change.required
+       - create types with slug, description, and readme
+\`\`\`
+
+---
+
+.ask =
+```md
+$.rhachet{ask}
+```
+
+.inflight? =
+```md
+$.rhachet{inflight}
+```
+
+.feedback? =
+```md
+$.rhachet{feedback}
+```
+
+.output = structured roadmap in decomposable milestone format. if inflight is provided, update it based on the feedback

package/dist/logic/roles/designer/outlineVision/stepOutlineVision.template.md

@@ -0,0 +1,47 @@
+@[designer]<outline><vision> for [desire]
+
+---
+
+.intent
+- clarify the **core intent** of the desired system or product
+- define the **irreducible constraints** that must be respected
+- surface the **essential shape** implied by the intent
+- identify **open space** — parts left intentionally flexible or undecided
+
+---
+
+.format
+\`\`\`md
+# 🎯 intent
+- {short summary of what the system is trying to make possible}
+
+# 📏 constraints
+- {things this system must respect — e.g., must run as CLI, must not leak domain logic}
+
+# 🧩 implied shape
+- [resource] — {core object this system revolves around}
+- <mechanism> — {core transformation it must enable}
+- {driver} — {why this system is needed now}
+
+# 🔮 open space
+- {what’s not yet decided — interface, delivery method, structure, etc.}
+\`\`\`
+
+---
+
+.ask =
+\`\`\`md
+$.rhachet{desire}
+\`\`\`
+
+.inflight? =
+\`\`\`md
+$.rhachet{inflight}
+\`\`\`
+
+.feedback? =
+\`\`\`md
+$.rhachet{feedback}
+\`\`\`
+
+.output = a distilled vision summary with core intent, constraints, implied shape, and open space; if inflight provided, respond to the feedback

package/dist/logic/roles/ecologist/.briefs/.readme.md

@@ -0,0 +1,17 @@
+these are the briefs that are relevant to the ecologist role
+
+.scratch has inflight and deprecated briefs
+
+directories group briefs by relevance
+
+root may also have some ungrouped ones
+
+---
+
+look for ._.summary.md briefs for compressed representations
+
+---
+
+we try and declare briefs as if they were courses in college
+
+it's a pattern ghia imagined, and has a good parallel, as our aim is to distill as informative and useful of a brief as possible -> distill lessons