@jaybeeuu/agent-cortex 1.38.1 → 1.39.0

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)
+```

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

@@ -1,86 +1,79 @@
 ---
 name: technical-direction
-description: Drive collaborative technical design by challenging assumptions, mapping constraints, comparing alternatives, and producing a justified recommendation. Use when user wants to decide technical direction after PRD, evaluate architecture/technology choices, or asks to design a solution with tradeoff analysis.
+description: Challenge assumptions, map constraints, compare options, and justify the choice. Use when deciding technical direction, choosing architecture or technology, or designing a solution with tradeoffs.
 ---
 
 # Technical Direction
 
-Act like a pragmatic, challenging staff engineer: constructive, direct, evidence-driven.
+Act as a pragmatic, challenging staff engineer: constructive, direct, and evidence-driven. The deliverable is a justified recommendation, not consensus.
+
+## When to use
+
+- "Decide technical direction" for a change with real architectural weight.
+- Evaluating architecture or technology choices that carry tradeoffs.
+- A PRD or brief is approved and the solution shape is still open.
+- "Design a solution" where alternatives need mapping and comparison before picking one.
+
+## When NOT to use
+
+- Stress-testing an existing plan or sharpening domain language — use `grill-with-docs`.
+- Scoping a feature into PRD and tasks — use `plan` before direction makes sense.
+- Exploring a codebase for refactoring opportunities — use `improve-codebase-architecture`.
+- Reversible decisions with no meaningful tradeoffs — a memo costs more than it saves.
 
 ## Workflow
 
-1. **Anchor on problem context**
-   - Start from PRD or user brief
-   - Confirm technical goals, non-goals, and decision horizon
-
-2. **Discover constraints from codebase first**
-   - Investigate architecture, existing interfaces, deployment/runtime constraints, data model boundaries, and team conventions
-   - Note unknowns and risks
-
-3. **Challenge loop (one question at a time)**
-   - Ask focused, high-leverage questions
-   - Challenge vague claims and hidden assumptions
-   - Require explicit justification for each major decision
-   - Keep drilling until constraints and tradeoffs are concrete
-
-4. **Generate options**
-   - Always include Option A (extend current approach), Option B (moderate architectural shift), and Option C (stronger alternative using new tech/pattern)
-   - For each option: feasibility, complexity, migration cost, operational impact, testability, performance, and failure modes
-
-5. **Use web research when needed**
-   - Do this autonomously when codebase evidence is insufficient or a high-impact decision needs external comparison
-   - Prefer authoritative sources (official docs, maintainers, widely adopted production guidance)
-   - Bring findings back as tradeoffs, and retain source links as references
-
-6. **Converge on a recommendation**
-   - Select the best-fit option for current constraints
-   - Explicitly explain why alternatives were not chosen
-   - List decision triggers that would justify revisiting later
-
-7. **Write decision memo**
-   - Ensure `docs/technical-direction/` exists
-   - Save to `docs/technical-direction/<feature-slug>.md` using this template:
-
-```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)
-```
-
-## Rules
-
-- Ask questions one at a time.
-- If the answer exists in the codebase, investigate before asking.
-- Be challenging but collaborative; do not optimize for agreement.
-- Avoid premature implementation details until direction is selected.
-- Every recommendation must include explicit constraints and tradeoffs.
-- When web or code sources materially inform decisions, include them in `## References`.
+1. **Anchor on problem context.** Start from the PRD or user brief. Confirm goals, non-goals, and the decision horizon (how long this choice must hold).
+2. **Discover constraints from the codebase first.** Investigate architecture, existing interfaces, deployment and runtime constraints, data-model boundaries, and team conventions using {{TOOL:rg}}, {{TOOL:view}}, and {{TOOL:glob}}. Record unknowns and risks explicitly.
+3. **Run the challenge loop, one question at a time.** Ask focused, high-leverage questions. Challenge vague claims and hidden assumptions; require explicit justification for each major decision. Keep drilling until constraints and tradeoffs are concrete. If an answer exists in the codebase, find it before asking.
+4. **Generate options.** Always include Option A (extend the current approach), Option B (moderate architectural shift), and Option C (a stronger alternative using new tech or patterns). Evaluate each on feasibility, complexity, migration cost, operational impact, testability, performance, and failure modes.
+5. **Use web research when the codebase is insufficient.** Do this autonomously for high-impact decisions needing external comparison. Prefer authoritative sources (official docs, maintainers, widely adopted production guidance) via {{TOOL:web_fetch}}; bring findings back as tradeoffs with source links.
+6. **Converge on a recommendation.** Select the best-fit option under current constraints. Explain explicitly why each alternative was not chosen. List decision triggers that would justify revisiting.
+7. **Write the decision memo.** Ensure `docs/technical-direction/` exists and save `docs/technical-direction/<feature-slug>.md` using the template in [FORMAT.md](FORMAT.md).
+
+## Red Flags
+
+- Red flag: proposing options before constraints are mapped — alternatives become uncomparable.
+- Red flag: asking a question the codebase can answer without looking first.
+- Red flag: optimising for agreement instead of surfacing hard tradeoffs.
+- Red flag: recommending direction without stated tradeoffs, revisit triggers, or validation signals.
+- Red flag: sliding into premature implementation details before direction is selected.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "We already know the answer" | Stated answers often rest on unstated assumptions. Test the recommendation against the constraints before accepting it. |
+| "The tradeoffs are obvious" | Obvious today is forgotten in a month. The memo exists so reversible choices stay reversible and irreversible ones are signposted. |
+| "Web research is overkill" | For high-impact choices with insufficient codebase evidence, external comparison is the cheapest way to kill a plausible-but-wrong option. |
+| "One option is clearly right" | A single option is a statement, not a decision. Alternatives and their failure modes are what justify the choice. |
+
+## Philosophy / rationale
+
+- **Constraints first, options second.** Options only compare against the constraints that bound them, so map the codebase and decision horizon before generating alternatives.
+- **Challenge is the deliverable.** The value of a direction session is the assumptions it surfaces and kills. Optimising for agreement produces a recommendation nobody tested.
+- **Every recommendation carries its tradeoffs.** A choice without documented tradeoffs, revisit triggers, and validation signals cannot be revisited intelligently later.
+
+## Cross-skill references
+
+- `write-a-prd` produces the input brief when no PRD exists yet.
+- `grill-with-docs` sharpens contested terminology and stress-tests the memo against domain docs.
+- `design-an-interface` structures the option-generation step when the decision is about interface shape.
+- `style-documentation` governs the memo's what/whether criteria before writing.
+
+## Examples
+
+Input: "Decide on the write-path storage for the events service."
+Output: a decision memo at `docs/technical-direction/events-write-path.md` covering constraints, three options scored against them, a justified recommendation, tradeoffs accepted, a validation plan, revisit triggers, and references. See [FORMAT.md](FORMAT.md) for the full template.
+
+## Verification checklist
+
+- [ ] Goals, non-goals, and decision horizon confirmed before options were generated
+- [ ] Codebase constraints explored before asking questions; unknowns and risks recorded
+- [ ] Questions asked one at a time; nothing answerable from the codebase asked of the user
+- [ ] At least three options considered, including an extend-current approach and a stronger alternative
+- [ ] Each option scored on feasibility, complexity, migration cost, operational impact, testability, performance, and failure modes
+- [ ] Recommendation states why alternatives were not chosen and lists revisit triggers
+- [ ] Decision memo saved to `docs/technical-direction/<feature-slug>.md` using the FORMAT.md template
+- [ ] Tradeoffs accepted, validation plan, and references (web and code, with links) included
+- [ ] No premature implementation detail in the memo — direction only