@jaybeeuu/agent-cortex 1.38.1 → 1.40.0

package/skills/engineering/design-an-interface/SKILL.md

@@ -1,94 +1,114 @@
 ---
 name: design-an-interface
-description: Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".
+description: "Generate multiple radically different interface designs for a module via parallel sub-agents, then compare and synthesize. Use when designing an API, exploring interface options, or \"design it twice\"."
 ---
 
 # Design an Interface
 
-Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
+## When to use
 
-## Workflow
-
-### 1. Gather Requirements
+- The user wants to design an API, module boundary, or public interface.
+- The user asks to explore interface options or compare module shapes.
+- The user mentions "design it twice" or says the first idea is unlikely to be the best.
+- An interface design step needs a guided parallel exploration — `improve-codebase-architecture` invokes this skill for its multi-design step.
 
-Before designing, understand:
+## When NOT to use
 
-- [ ] What problem does this module solve?
-- [ ] Who are the callers? (other modules, external users, tests)
-- [ ] What are the key operations?
-- [ ] Any constraints? (performance, compatibility, existing patterns)
-- [ ] What should be hidden inside vs exposed?
+- The user wants a single justified recommendation with tradeoff analysis — use `technical-direction` instead.
+- The module's shape is already fixed by an upstream contract or framework, so exploring alternatives is wasted effort.
+- The question is about implementation strategy, not interface shape.
 
-Ask: "What does this module need to do? Who will use it?"
+## Philosophy / rationale
 
-### 2. Generate Designs (Parallel Sub-Agents)
+- **Your first idea is unlikely to be the best.** "Design It Twice" (John Ousterhout, *A Philosophy of Software Design*) holds that the first design is almost never the strongest. Generating multiple radically different candidates forces the comparison that finds the best shape.
+- **Contrast, not volume, creates insight.** Similar designs from parallel agents only confirm one idea. Each agent is assigned a different constraint so divergence is guaranteed by construction.
+- **Interface shape is the whole problem here.** The process stops at the interface — implementation effort is irrelevant to the comparison, because a good interface usually makes the implementation easier, not harder. Judging designs by implementation cost rewards shallow modules.
 
-Spawn 3+ sub-agents simultaneously using {{TOOL:task}}. Each must produce a **radically different** approach.
+## Workflow
 
-```
-Prompt template for each sub-agent:
+1. **Gather requirements.** Before designing, pin down:
+   - What problem does the module solve?
+   - Who are the callers (other modules, external users, tests)?
+   - What are the key operations?
+   - What constraints apply (performance, compatibility, existing patterns)?
+   - What should be hidden inside vs exposed?
 
-Design an interface for: [module description]
+   Ask: "What does this module need to do? Who will use it?"
 
-Requirements: [gathered requirements]
+2. **Generate designs with parallel sub-agents.** Spawn 3+ sub-agents simultaneously with {{TOOL:task}}, each assigned a **different** constraint to guarantee radical difference. Use this prompt template per agent:
 
-Constraints for this design: [assign a different constraint to each agent]
-- Agent 1: "Minimize method count - aim for 1-3 methods max"
-- Agent 2: "Maximize flexibility - support many use cases"
-- Agent 3: "Optimize for the most common case"
-- Agent 4: "Take inspiration from [specific paradigm/library]"
+   ```
+   Design an interface for: [module description]
 
-Output format:
-1. Interface signature (types/methods)
-2. Usage example (how caller uses it)
-3. What this design hides internally
-4. Trade-offs of this approach
-```
+   Requirements: [gathered requirements]
 
-### 3. Present Designs
+   Constraints for this design: [assign a different constraint to each agent]
+   - Agent 1: "Minimize method count — aim for 1-3 methods max"
+   - Agent 2: "Maximize flexibility — support many use cases"
+   - Agent 3: "Optimize for the most common case"
+   - Agent 4: "Take inspiration from [specific paradigm/library]"
 
-Show each design with:
+   Output format:
+   1. Interface signature (types/methods)
+   2. Usage example (how a caller uses it)
+   3. What this design hides internally
+   4. Trade-offs of this approach
+   ```
 
-1. **Interface signature** - types, methods, params
-2. **Usage examples** - how callers actually use it in practice
-3. **What it hides** - complexity kept internal
+   Collect each agent's output with {{TOOL:read_agent}} when it finishes.
 
-Present designs sequentially so user can absorb each approach before comparison.
+3. **Present designs.** Show each design sequentially — signature, usage examples, what it hides — so the user absorbs each approach before any comparison happens.
 
-### 4. Compare Designs
+4. **Compare designs.** Compare in prose, not tables, on:
+   - **Interface simplicity** — fewer methods, simpler params
+   - **General-purpose vs specialized** — flexibility vs focus
+   - **Implementation efficiency** — does the shape allow efficient internals?
+   - **Depth** — small interface hiding significant complexity (deep module, good) vs large interface with thin implementation (shallow module, avoid)
+   - **Ease of correct use** vs ease of misuse
 
-After showing all designs, compare them on:
+   Highlight where the designs diverge most — that divergence is where the decision lives.
 
-- **Interface simplicity**: fewer methods, simpler params
-- **General-purpose vs specialized**: flexibility vs focus
-- **Implementation efficiency**: does shape allow efficient internals?
-- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
-- **Ease of correct use** vs **ease of misuse**
+5. **Synthesize.** Ask: "Which design best fits your primary use case?" and "What elements from other designs are worth incorporating?" Often the best design combines insights from multiple options.
 
-Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
+## Red Flags
 
-### 5. Synthesize
+- **Sub-agents converging on similar designs** — if two agents produce near-identical shapes, re-run with sharper, more opposed constraints. Similarity means the contrast step lost its value.
+- **Skipping comparison** — jumping from presentation to a favorite design discards the whole point of exploring alternatives.
+- **Sliding into implementation** — this process concerns interface shape only. Implementation details belong in a follow-up task.
+- **Judging designs by implementation effort** — a design that looks harder to build may still be the deeper, better interface.
 
-Often the best design combines insights from multiple options. Ask:
+## Common Rationalizations
 
-- "Which design best fits your primary use case?"
-- "Any elements from other designs worth incorporating?"
+| Rationalization | Rebuttal |
+|---|---|
+| "My first design is probably fine" | That is exactly the assumption "design it twice" exists to break. Generate the alternatives before committing. |
+| "The agents will just produce similar things, so why bother" | Similarity is a failure mode you control — assign opposed constraints so divergence is guaranteed by construction. |
+| "I can compare these myself, no need to present each one" | Sequential presentation forces you to articulate what each design actually is before judging it, which is where the insight comes from. |
 
-## Evaluation Criteria
+## Phase-gate checklists
 
-From "A Philosophy of Software Design":
+- [ ] Phase 1 complete: requirements gathered and constraints listed
+- [ ] Phase 2 complete: 3+ designs returned, each constrained differently
+- [ ] Phase 3 complete: all designs presented sequentially
+- [ ] Phase 4 complete: comparison shared and divergence highlighted
+- [ ] Phase 5 complete: candidate synthesized with user input
 
-**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
+## Cross-skill references
 
-**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
+- `improve-codebase-architecture` invokes this skill for its multi-design step (step 5 of its workflow).
+- Run `grill-with-docs` when the module's domain terminology is unsettled — design names should match the ubiquitous language.
 
-**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
+## Examples
 
-**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
+Input: "Design the interface for a rate limiter module"
+Output: four radically different interface sketches (minimal-method, flexible, common-case-optimized, paradigm-inspired), presented sequentially, compared on simplicity, depth, and trade-offs, then synthesized into one recommended shape with the user.
 
-## Anti-Patterns
+## Verification checklist
 
-- Don't let sub-agents produce similar designs - enforce radical difference
-- Don't skip comparison - the value is in contrast
-- Don't implement - this is purely about interface shape
-- Don't evaluate based on implementation effort
+- [ ] Requirements captured before any sub-agent is spawned
+- [ ] At least 3 sub-agents spawned, each with a distinct constraint
+- [ ] Each design reports signature, usage example, hidden complexity, and trade-offs
+- [ ] Designs presented sequentially before any comparison
+- [ ] Comparison covers simplicity, generality, efficiency, depth, and ease of correct use
+- [ ] Synthesis asks the user which design fits their primary use case
+- [ ] No implementation work performed — interface shape only

package/skills/engineering/grill-with-docs/REFERENCE.md

@@ -0,0 +1,78 @@
+# Grill-with-docs reference
+
+Rarely-needed detail the workflow points to when you must create or update project documents.
+
+## Finding the domain model
+
+### Single-context repos
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+### Multi-context repos
+
+A `CONTEXT-MAP.md` at the root points to where each context lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                      ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/             ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term resolves. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## CONTEXT.md entry format
+
+One `# term` heading per entry with a plain-prose definition and cross-links to related terms:
+
+```md
+# cancellation
+An order may be cancelled only before fulfilment begins. See refund for the
+post-fulfilment reversal path.
+```
+
+Rules:
+
+- Glossary only — no implementation details, no specs, no scratch notes.
+- Prefer one concise definition over long paragraphs.
+- Cross-link related terms so the vocabulary is navigable.
+
+## ADR format
+
+One file per decision in `docs/adr/`, zero-padded sequence number plus kebab-case title:
+
+```
+0003-cancel-before-fulfilment-only.md
+```
+
+Structure:
+
+```md
+# Title
+
+## Context
+What problem forced the decision and why the question arose.
+
+## Decision
+The choice, stated precisely.
+
+## Consequences
+What becomes easier or harder as a result; what a future reader must know.
+```
+
+Offer an ADR only when all three hold — hard to reverse, surprising without context, real trade-off. If any is missing, skip it.

package/skills/engineering/grill-with-docs/SKILL.md

@@ -1,88 +1,91 @@
 ---
 name: grill-with-docs
-description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+description: "Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when the user wants to stress-test a plan against their project's language and documented decisions: \"grill my plan\", \"check this against our docs\"."
 ---
 
-<what-to-do>
+# Grill With Docs
 
-Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+## When to use
 
-Ask the questions one at a time, waiting for feedback on each question before continuing.
+- The user wants to stress-test a plan against the project's existing language: "grill my plan", "grill me on this design".
+- Domain terms are fuzzy or drifting and you need to pin them against `CONTEXT.md`.
+- A decision needs recording as an ADR before the design moves on.
+- Invoked by `ralph-plan` when the domain language is unclear or inconsistent.
 
-If a question can be answered by exploring the codebase, explore the codebase instead.
+## When NOT to use
 
-</what-to-do>
+- Grilling a plan with no documentation dimension — use `grill-me` for a pure design interview.
+- Deciding architecture or technology trade-offs — use `technical-direction` for a justified recommendation.
+- Writing project docs without an interview; this skill extracts language from the user, it does not generate it.
 
-<supporting-info>
+## Workflow
 
-## Domain awareness
+1. **Load the domain model.** Locate and read `CONTEXT.md` (single context) or `CONTEXT-MAP.md` (multi-context; the map points to each context's glossary and `docs/adr/`). Read existing ADRs so you question from the project's actual vocabulary. If neither file exists, you are starting a fresh glossary.
+2. **Grill one question at a time.** State the decision branch, give your recommended answer, and wait for feedback before continuing. If a question can be answered by exploring the codebase, explore instead of asking.
+3. **Challenge against the glossary.** When a term conflicts with `CONTEXT.md`, call it out immediately: "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" When the user uses vague or overloaded terms, propose a precise canonical term.
+4. **Stress-test with concrete scenarios.** Probe domain relationships with invented edge cases that force precision about concept boundaries.
+5. **Cross-reference with code.** When the user states how something works, check whether the code agrees. Surface contradictions the moment you find them.
+6. **Update `CONTEXT.md` inline.** When a term resolves, write the entry right there — do not batch. Keep it a pure glossary: no implementation details, no specs, no scratch notes. Entry format and file-discovery rules live in `REFERENCE.md`.
+7. **Offer ADRs sparingly.** Propose an ADR only when all three hold: hard to reverse, surprising without context, and the result of a real trade-off. If any is missing, skip it. ADR format lives in `REFERENCE.md`.
+8. **Close when shared understanding is reached.** Confirm every design-tree branch is resolved or explicitly deferred, and that the glossary diff captures the session's new language.
 
-During codebase exploration, also look for existing documentation:
+## Red Flags
 
-### File structure
+- **Batching questions** — asking several at once lets the user answer the easy ones while the hard branch dies silently.
+- **Drifting into generic design Q&A** — every question must anchor in the domain model, not general software opinion.
+- **Deferring `CONTEXT.md` writes** — "I'll write it up later" loses the precision of the moment; terms resolved in context get reinterpreted from memory.
+- **Stuffing implementation detail into `CONTEXT.md`** — it is a glossary; specs and scratch notes belong elsewhere.
+- **Offering ADRs on autopilot** — an ADR for an easily-reversed choice bloats the log and buries the real decisions.
 
-Most repos have a single context:
+## Common Rationalizations
 
-```
-/
-├── CONTEXT.md
-├── docs/
-│   └── adr/
-│       ├── 0001-event-sourced-orders.md
-│       └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/
-│   └── adr/                          ← system-wide decisions
-├── src/
-│   ├── ordering/
-│   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← context-specific decisions
-│   └── billing/
-│       ├── CONTEXT.md
-│       └── docs/adr/
-```
-
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
-
-## During the session
-
-### Challenge against the glossary
+| Rationalization | Rebuttal |
+|---|---|
+| "I'll ask three questions at once to save a round trip" | Branches depend on each other's answers; batching forces guesswork. |
+| "We both know what this term means — no need to write it" | If you won't write it down, it isn't resolved; unwritten terms get relitigated. |
+| "This decision feels important, let me write an ADR" | Only hard-to-reverse, surprising, real-trade-off decisions earn an ADR. |
+| "The code contradicts you, but I'll note it later" | The contradiction changes the next answer — surface it now. |
 
-When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+## Philosophy / rationale
 
-### Sharpen fuzzy language
+- **One question at a time, with a recommended answer** — every exchange settles a branch instead of opening several, so shared understanding accumulates.
+- **Capture inline, not batched** — decisions recorded in context are precise; decisions reconstructed from memory drift.
+- **`CONTEXT.md` is a glossary and nothing else** — the vocabulary stays stable while the design churns around it.
+- **ADRs are rare** — the three criteria keep the ADR log a history of decisions, not a diary.
 
-When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+## Cross-skill references
 
-### Discuss concrete scenarios
+| When you need… | Use |
+|---|---|
+| A design interview without touching project docs | `grill-me` |
+| A justified recommendation on architecture or technology | `technical-direction` |
 
-When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+## Examples
 
-### Cross-reference with code
+**Sharpening a fuzzy term**
 
-When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
-
-### Update CONTEXT.md inline
-
-When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
-
-`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
-
-### Offer ADRs sparingly
+```
+User: "So cancelled orders can still ship."
+You:  "CONTEXT.md defines cancellation as 'void before fulfilment begins'.
+       What you describe is reversing after shipping — that's a refund. Which is it?"
+User: "A refund."
+```
 
-Only offer to create an ADR when all three are true:
+Entry appended to CONTEXT.md the moment it resolves:
 
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
-3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+```
+# refund
+Reversal of an order after fulfilment has begun. Distinct from cancellation,
+which voids an order before fulfilment. See cancellation.
+```
 
-If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
+## Verification checklist
 
-</supporting-info>
+- [ ] Questions asked one at a time, each with a recommended answer
+- [ ] Every question answerable by code was explored in the codebase instead
+- [ ] Each resolved term written to `CONTEXT.md` during the session — none batched at the end
+- [ ] `CONTEXT.md` holds only glossary entries — no implementation detail, specs, or scratch notes
+- [ ] Terminology conflicts and vague terms called out the moment they appeared
+- [ ] Claims cross-referenced against code; contradictions surfaced
+- [ ] ADRs offered only when all three criteria held (offering none is a valid outcome)
+- [ ] All design-tree branches resolved or explicitly deferred before closing

package/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -1,81 +1,99 @@
 ---
 name: improve-codebase-architecture
-description: Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.
+description: Explore a codebase to surface architectural friction and turn it into module-deepening refactors that improve testability and AI-navigability. Use when the user wants to improve the architecture, find refactoring opportunities, consolidate tightly-coupled modules, or says a codebase is hard to navigate.
 ---
 
 # Improve Codebase Architecture
 
-Explore a codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors as beads.
+Explore a codebase the way an AI would, surface where understanding requires bouncing between many small files, and propose module-deepening refactors as executable beads.
 
-A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside.
+A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and testable at the boundary instead of inside the seams.
 
-## Process
+## When to use
 
-### 1. Explore the codebase
+- The user wants to improve the architecture or find refactoring opportunities.
+- The user asks to consolidate tightly-coupled modules or "make this more testable".
+- The user says a codebase is "hard to navigate" or hard for AI to work with.
 
-Explore the codebase using your available tools ({{TOOL:bash}}, {{TOOL:rg}}, {{TOOL:view}}, {{TOOL:glob}}). Navigate organically and note where you experience friction:
+## When NOT to use
 
-- Where does understanding one concept require bouncing between many small files?
-- Where are modules so shallow that the interface is nearly as complex as the implementation?
-- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
-- Where do tightly-coupled modules create integration risk in the seams between them?
-- Which parts of the codebase are untested, or hard to test?
+- The refactor target is decided and only an implementation plan is missing — run `request-refactor-plan` instead.
+- The task is comparing two specific options with trade-offs — run `technical-direction` instead.
+- The user wants interface shapes for one known module — run `design-an-interface` instead.
+- The work is a new feature needing scoping — run `plan` or `write-a-prd` instead.
 
-The friction you encounter IS the signal.
+## Workflow
 
-### 2. Present candidates
+1. **Explore the codebase.** Navigate with {{TOOL:bash}}, {{TOOL:rg}}, {{TOOL:view}}, and {{TOOL:glob}}, and note where you experience friction: concepts spread across many small files, interfaces nearly as complex as their implementations, pure functions extracted for testability while bugs hide in their call sites, tight coupling creating integration risk, or untested hard-to-test areas. The friction you encounter is the signal — record it as you go.
 
-Present a numbered list of deepening opportunities. For each candidate, show:
+2. **Present candidates.** Give a numbered list of deepening opportunities. For each, show the cluster of modules involved, why they are coupled (shared types, call patterns, co-ownership of a concept), the dependency category (see [REFERENCE.md](REFERENCE.md)), and the test impact. Do not propose interfaces yet — ask "Which of these would you like to explore?"
 
-- **Cluster**: Which modules/concepts are involved
-- **Why they're coupled**: Shared types, call patterns, co-ownership of a concept
-- **Dependency category**: See [REFERENCE.md](REFERENCE.md) for the four categories
-- **Test impact**: What existing tests would be replaced by boundary tests
+3. **User picks a candidate.**
 
-Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+4. **Frame the problem space.** Before designing anything, write a user-facing frame for the chosen candidate: the constraints any new interface must satisfy, the dependencies it must rely on, and a rough illustrative code sketch. A sketch is not a proposal — it grounds the constraints. Show the frame and proceed immediately; the user reads it while you design.
 
-### 3. User picks a candidate
+5. **Design multiple interfaces.** Cycle through radically different constraints, writing each design out fully before the next:
 
-### 4. Frame the problem space
+   1. **Minimal** — aim for 1-3 entry points; what complexity hides behind a small surface?
+   2. **Flexible** — open for future use cases and extension.
+   3. **Caller-optimised** — make the most common calling pattern trivial.
+   4. **Ports & adapters** (if cross-boundary deps) — isolate side effects from pure logic.
 
-Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+   For each design, output the interface signature, a usage example, the complexity it hides, the dependency strategy (see [REFERENCE.md](REFERENCE.md)), and its trade-offs. Present designs sequentially, then compare them in prose and give your own recommendation — propose a hybrid where elements combine well. The user wants a strong read, not a menu.
 
-- The constraints any new interface would need to satisfy
-- The dependencies it would need to rely on
-- A rough illustrative code sketch to make the constraints concrete — this is not a proposal, just a way to ground the constraints
+6. **User picks an interface** (or accepts the recommendation).
 
-Show this to the user, then immediately proceed to Step 5. The user reads and thinks about the problem while the sub-agents work in parallel.
+7. **Create the refactor bead.** Run the `create-task` skill with a concise title, the description from the template in [REFERENCE.md](REFERENCE.md), and priority P2. Always use `create-task` — never `bd create` directly — because it classifies the bead and expands AFK work into pipeline stages ralph can execute. Do not ask the user to review before creating; share the bead ID.
 
-### 5. Design multiple interfaces
+## Red Flags
 
-Design multiple radically different interfaces for the deepened module yourself, cycling through different constraints. For each design, write out the complete interface and evaluate it before moving to the next:
+- Red flag: proposing an interface during candidate presentation — it biases which problem space the user picks.
+- Red flag: skipping the problem-space frame to save a step — designs without stated constraints drift.
+- Red flag: designing a single interface — the first design is rarely the strongest ("Design It Twice").
+- Red flag: filing the bead with `bd create` instead of `create-task` — the pipeline expansion is skipped.
+- Red flag: judging designs by implementation effort — a deeper interface often looks harder to build.
 
-1. **Minimal interface** — aim for 1-3 entry points max. What complexity can you hide behind a small surface area?
-2. **Flexible interface** — support many use cases and extension. How do you make it open for future needs?
-3. **Caller-optimised** — make the most common calling pattern trivial. What does the primary caller look like?
-4. **Ports & adapters** (if cross-boundary deps) — isolate side effects from pure logic.
+## Common Rationalizations
 
-For each design, output:
+| Rationalization | Rebuttal |
+|---|---|
+| "I already know the best interface" | The first design is rarely the best. Generating alternatives is where the comparison insight comes from. |
+| "The candidates are obvious — list them quickly" | The presentation is what lets the user pick deliberately; short-circuiting it forces a guess. |
+| "The problem space is clear enough — skip the frame" | An unframed design session produces interfaces that satisfy imagined constraints. |
+| "It's one task — `bd create` is fine" | `create-task` classifies the bead and expands pipeline stages; bypassing it strands the work for ralph. |
 
-1. Interface signature (types, methods, params)
-2. Usage example showing how callers use it
-3. What complexity it hides internally
-4. Dependency strategy (how deps are handled — see [REFERENCE.md](REFERENCE.md))
-5. Trade-offs
+## Philosophy / rationale
 
-The `design-an-interface` skill provides a structured approach for this step — invoke it if you want a guided parallel-design flow with sub-agents.
+- **Deep modules beat shallow ones.** A small interface hiding real complexity is easier to learn, test, and navigate; a shallow module forces callers to know as much as the implementation does.
+- **An AI's navigation friction is the signal.** Wherever exploration requires bouncing between files, a missing seam or a shallow module is hiding — the explorer's pain maps directly to where a deep module is needed.
+- **Replace, don't layer tests.** Once boundary tests exist at the deepened interface, the old shallow-module tests are waste — tests should assert observable outcomes through the public interface, not internal state.
+- **Candidate-first, interface-later.** Interfaces proposed before the user picks a problem space pre-commit the exploration to a shape they did not choose.
 
-Present designs sequentially, then compare them in prose.
+## Phase-gate checklists
 
-After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not just a menu.
+- [ ] Phase 1 complete: exploration done and candidates presented without proposing interfaces
+- [ ] Phase 2 complete: problem space framed and shown to the user before any design work
+- [ ] Phase 3 complete: at least two radically different designs presented and compared, with a recommendation given
+- [ ] Phase 4 complete: refactor bead created via `create-task` and the bead ID reported
 
-### 6. User picks an interface (or accepts recommendation)
+## Cross-skill references
 
-### 7. Create refactor bead
+- Run `design-an-interface` at step 5 for a guided parallel sub-agent design flow.
+- Run `create-task` at step 7 to file the refactor bead.
+- Run `grill-with-docs` when the deepened module's terminology is unsettled — interface names should match the ubiquitous language.
 
-Invoke the `create-task` skill, passing:
-- **title**: a concise name for the refactor
-- **description**: the bead body using the template in [REFERENCE.md](REFERENCE.md)
-- **priority**: P2
+## Examples
 
-**Always use `create-task`** — never call `bd create` directly for tasks. `create-task` classifies the bead and expands AFK tasks into pipeline stage children that ralph can execute. Do NOT ask the user to review before creating — just create it and share the bead ID.
+Input: "This codebase is hard to navigate — can you make it more testable?"
+Output: numbered deepening candidates (cluster, coupling, dependency category, test impact) → chosen candidate → problem-space frame → at least two interface designs with a recommendation → a P2 refactor bead ID from `create-task`, with the bead description following the template in [REFERENCE.md](REFERENCE.md).
+
+## Verification checklist
+
+- [ ] Friction notes recorded during exploration
+- [ ] Candidates presented with cluster, coupling, dependency category, and test impact — no interfaces proposed
+- [ ] Problem-space frame shown to the user before any design work
+- [ ] At least two radically different designs, each with signature, usage example, hidden complexity, dependency strategy, and trade-offs
+- [ ] Recommendation given in prose, with a hybrid proposed where elements combine well
+- [ ] Refactor bead created via `create-task` at P2 using the REFERENCE.md description template
+- [ ] Bead ID reported and no review gate imposed before creation
+- [ ] No unrelated areas explored or refactors proposed outside the chosen candidate

package/skills/engineering/technical-direction/FORMAT.md

@@ -0,0 +1,38 @@
+# Decision Memo Format
+
+The decision memo is the deliverable of `technical-direction`. Save it as `docs/technical-direction/<feature-slug>.md`:
+
+```md
+# Technical Direction: <Feature Name>
+## Problem and target outcome
+- What we are solving
+- Why this matters now
+## Current-state constraints
+- Architecture and integration constraints
+- Team/runtime/operational constraints
+- Unknowns and assumptions
+## Options considered
+### Option A: <name>
+- Approach
+- Pros
+- Cons
+- Risks
+### Option B: <name>
+...
+### Option C: <name>
+...
+## Recommendation
+- Chosen approach
+- Why this is best under current constraints
+- Why alternatives were not selected
+## Tradeoffs accepted
+- Explicit compromises and consequences
+## Validation plan
+- Fastest experiments/spikes to de-risk decision
+- Success/failure signals
+## Revisit triggers
+- Conditions that should force re-evaluation
+## References
+- Web sources used for decisions (title + URL)
+- Code evidence links (repo path + line range, and permalink URL when available)
+```