@martinffx/atelier 1.1.0 → 1.2.0

package/skills/oracle-architect/SKILL.md

@@ -6,6 +6,24 @@ user-invocable: false
 
 # Architect Skill
 
+## Glossary
+
+Precise vocabulary for every architectural decision. Use these terms exactly — consistency is the point.
+
+- **Module** — anything with an interface and an implementation (function, class, package, layer). Router, Service, Entity, and Repository are all modules.
+- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
+- **Seam** — where a module's interface lives; a place behaviour can be altered without editing in place. The functional core / effectful edge boundary is the primary seam.
+- **Depth** — leverage at the interface. A module is **deep** when a lot of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
+- **Adapter** — a concrete thing satisfying an interface at a seam. A Postgres repository is an adapter; an in-memory fake for testing is another adapter at the same seam.
+- **Leverage** — what callers get from depth: more capability per unit of interface they learn.
+- **Locality** — what maintainers get from depth: change, bugs, and knowledge concentrate in one place.
+
+Key principles (apply to every decision):
+
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.
+- **One adapter = hypothetical seam. Two adapters = real seam.** Don't introduce a seam unless something actually varies across it.
+
 Domain-Driven Design and hexagonal architecture with functional core pattern for feature design.
 
 ## Architecture Model
@@ -25,6 +43,68 @@ Unified view of functional core and effectful edge:
 
 **Key Principle:** Business logic lives in the functional core (Service + Entity). IO operations live in the effectful edge. Core defines interfaces; edge implements them (dependency inversion).
 
+## Evaluating Architecture Decisions
+
+Before creating a new module, run these checks:
+
+### Deletion Test
+
+> *Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.*
+
+**When to apply:** Before extracting a new Service, Repository, or utility class.
+
+**Example:**
+```
+❌ Shallow: OrderFormatterService with 1 method per field
+   → Deleting it just moves 6 lines into the Router
+   → Interface is as complex as implementation
+
+✅ Deep: OrderService with validate → reserve → save → publish
+   → Deleting it replicates orchestration across N handlers
+   → Small interface (createOrder), large implementation
+```
+
+### Interface as Test Surface
+
+> *Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.*
+
+**Implication:**
+- Unit tests for Entities test the public interface (validate, transform)
+- Unit tests for Services test through the seam with stub repositories
+- Integration tests for Repositories test the actual adapter
+- If you find yourself testing "internal" methods, the module needs redrawing
+
+### Adapter Rule
+
+> *One adapter = hypothetical seam. Two adapters = real seam.*
+
+**When to apply:** Deciding whether to extract an interface.
+
+**Examples:**
+```typescript
+// ❌ Hypothetical seam — only one adapter exists
+interface IEmailClient { send(email: Email): Promise<void>; }
+class SendgridClient implements IEmailClient { ... }
+// No second adapter. The interface adds indirection without value.
+
+// ✅ Real seam — two adapters exist
+interface IOrderRepository { save(order: Order): Promise<Order>; }
+class PostgresOrderRepository implements IOrderRepository { ... }
+class InMemoryOrderRepository implements IOrderRepository { ... } // for tests
+// The seam earns its keep because callers vary (production vs test).
+```
+
+### Depth Check
+
+Prefer deep modules over shallow ones:
+
+| Module | Interface Size | Implementation | Depth |
+|--------|--------------|----------------|-------|
+| `OrderValidator` | 3 methods (validate, validateItems, validateAddress) | 30 lines each | Shallow |
+| `Order` (entity) | 4 methods (fromRequest, toRecord, toResponse, validate) | 200 lines of rules, transforms, invariants | **Deep** |
+
+**Rule of thumb:** A module's interface should hide at least 3x the complexity it exposes.
+
 ## Functional Core
 
 Pure, deterministic components containing all business logic.
@@ -241,6 +321,7 @@ The testing skill uses architectural structure to determine:
 
 For detailed patterns and examples:
 
-- **See [references/ddd-patterns.md](references/ddd-patterns.md)** - Aggregates, Value Objects, Domain Events, Bounded Contexts, composition patterns
+- **See [references/ddd-patterns.md](references/ddd-patterns.md)** - Aggregates, Value Objects, Domain Events, Bounded Contexts, composition patterns, seam placement
 - **See [references/data-modeling.md](references/data-modeling.md)** - Entity design principles, schema patterns, access pattern optimization, data transformation
 - **See [references/api-design.md](references/api-design.md)** - REST conventions, request/response contracts, error handling, versioning patterns
+- **See [references/interface-design.md](references/interface-design.md)** - Designing module interfaces, "Design It Twice" pattern, depth heuristics, dependency categories, anti-patterns

package/skills/oracle-architect/references/ddd-patterns.md

@@ -245,3 +245,104 @@ Bounded Context: "Orders"
 3. **Aggregate → Repository**: Service uses repository to persist aggregate
 4. **Service → Producer**: Service publishes domain events after state change
 5. **Consumer → Service**: Events from other contexts trigger service operations
+
+## Seam Placement
+
+Where you put the seam matters as much as what goes behind it.
+
+### Core/Edge Seam
+
+The primary seam runs between the functional core and the effectful edge:
+
+```
+┌─────────────────────────────────┐
+│  Functional Core (pure)         │
+│  ┌──────────────────────────┐   │
+│  │ OrderService             │   │
+│  │   createOrder() ────────┼───┼──▶ (seam)
+│  │   processPayment()       │   │
+│  └──────────────────────────┘   │
+└─────────────────────────────────┘
+              │
+              ▼ seam
+┌─────────────────────────────────┐
+│  Effectful Edge (IO)            │
+│  ┌──────────────────────────┐   │
+│  │ PostgresOrderRepository  │◀──┼── adapter
+│  │ HttpPaymentClient        │   │   adapter
+│  │ InMemoryOrderRepository  │   │   adapter (test)
+│  └──────────────────────────┘   │
+└─────────────────────────────────┘
+```
+
+**Rules:**
+- Core defines the interface; edge implements it (dependency inversion)
+- The seam must have **at least two adapters** to be real (production + test)
+- Core never imports edge code; edge imports core interfaces
+
+### Internal Seams
+
+A deep module can have **internal seams** — private to its implementation, used by its own tests:
+
+```typescript
+class Order {
+  // External seam (public interface)
+  validate(): Result<Order> { ... }
+
+  // Internal seam (private, tested directly)
+  private calculateTax(subtotal: number): Money { ... }
+}
+```
+
+Internal seams let you test complex logic without exposing it in the public interface.
+
+### When to Create a Seam
+
+Use the **adapter rule**: one adapter = hypothetical; two = real.
+
+| Scenario | Action |
+|----------|--------|
+| One database implementation, no test fake | No seam needed. Direct dependency is simpler. |
+| One database implementation, test fake exists | Extract interface. The fake is the second adapter. |
+| Multiple database implementations (Postgres + DynamoDB) | Extract interface. The implementations are the adapters. |
+| External API with one client | Direct dependency. Introduce seam only when you need a mock/stub for testing. |
+
+### Anti-Patterns
+
+**Seam at every dependency:**
+```typescript
+// ❌ Too many seams — every dependency gets an interface
+interface IValidator { ... }
+interface IFormatter { ... }
+interface IConverter { ... }
+// Each has one adapter. Indirection without value.
+```
+
+**No seam at the core/edge boundary:**
+```typescript
+// ❌ Core imports edge directly
+import { db } from '../edge/postgres';
+class OrderService {
+  async createOrder(req) {
+    await db.orders.create(...); // Core knows about Postgres
+  }
+}
+```
+
+**Leaky seam:**
+```typescript
+// ❌ Interface exposes implementation details
+interface OrderRepository {
+  queryRaw(sql: string): Promise<Row[]>; // Caller knows SQL
+  beginTransaction(): Promise<Transaction>; // Caller manages transactions
+}
+// The seam leaks. Callers become coupled to the database.
+```
+
+### Seam Placement Checklist
+
+Before introducing a new seam, verify:
+- [ ] At least two adapters will exist (production + test, or multiple production)
+- [ ] The interface hides implementation details (no SQL, no HTTP, no framework types)
+- [ ] The core doesn't import edge code
+- [ ] Deleting the module would re-appear complexity across N callers

package/skills/oracle-architect/references/interface-design.md

@@ -0,0 +1,203 @@
+# Interface Design Reference
+
+Patterns for designing module interfaces that maximize depth, leverage, and locality.
+
+Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+## Design It Twice
+
+Before committing to a module's interface, sketch at least two alternatives with different trade-offs.
+
+### Process
+
+1. **Frame the problem space**
+   - List constraints any interface must satisfy
+   - Identify dependencies and which category they fall into
+   - Write a rough illustrative code sketch to ground the constraints
+
+2. **Sketch alternatives**
+   - Alternative A: Minimize the interface (1–3 entry points max)
+   - Alternative B: Maximize flexibility (support many use cases)
+   - Alternative C: Optimize for the most common caller (default case trivial)
+
+3. **Compare by depth**
+   - Which alternative has the smallest interface for the most behaviour?
+   - Which concentrates the most knowledge in one place?
+   - Which has the best test surface?
+
+### Example: Order Creation Interface
+
+**Problem:** Design the interface for creating an order.
+
+**Alternative A — Minimal interface:**
+```typescript
+interface OrderService {
+  createOrder(request: CreateOrderRequest): Promise<Result<Order>>;
+}
+```
+- **Pros:** Tiny surface. One seam. Easy to mock.
+- **Cons:** All complexity hidden inside. Hard to test partial flows (e.g. validation without persistence).
+- **Depth:** Very deep. High leverage, high locality.
+
+**Alternative B — Flexible interface:**
+```typescript
+interface OrderService {
+  validate(request: CreateOrderRequest): Promise<Result<Order>>;
+  reserveInventory(order: Order): Promise<Result<Order>>;
+  save(order: Order): Promise<Result<Order>>;
+  publishEvents(order: Order): Promise<void>;
+}
+```
+- **Pros:** Callers compose their own flows. Easy to test each step.
+- **Cons:** Interface is as complex as implementation. Callers must know ordering constraints (reserve before save).
+- **Depth:** Shallow. Low leverage — callers replicate orchestration.
+
+**Alternative C — Optimized for common case:**
+```typescript
+interface OrderService {
+  createOrder(request: CreateOrderRequest): Promise<Result<Order>>;
+  createOrderDraft(request: CreateOrderRequest): Promise<Result<Order>>; // no inventory check
+  confirmOrder(orderId: string): Promise<Result<Order>>; // draft → confirmed
+}
+```
+- **Pros:** Common case (createOrder) is trivial. Draft pattern supports async workflows.
+- **Cons:** More surface area than Alternative A. Callers must understand draft vs confirmed.
+- **Depth:** Moderate. Good leverage for the common case.
+
+**Recommendation:** Alternative C. It balances depth with real workflow needs. The draft/confirm split is a real seam (two callers: interactive vs batch).
+
+## Interface Size Heuristics
+
+### The Rule of Three
+
+A module's public interface should have no more than 3 primary entry points for each responsibility:
+
+```typescript
+// ❌ Too wide
+interface OrderService {
+  createOrder(...): Promise<Order>;
+  updateOrder(...): Promise<Order>;
+  deleteOrder(...): Promise<void>;
+  getOrder(...): Promise<Order>;
+  listOrders(...): Promise<Order[]>;
+  searchOrders(...): Promise<Order[]>;
+  cancelOrder(...): Promise<Order>;
+  shipOrder(...): Promise<Order>;
+  refundOrder(...): Promise<Order>;
+}
+
+// ✅ Split by responsibility (2 modules, each with ~3 methods)
+interface OrderLifecycleService {
+  create(...): Promise<Order>;
+  cancel(...): Promise<Order>;
+  ship(...): Promise<Order>;
+}
+
+interface OrderQueryService {
+  get(id: string): Promise<Order>;
+  list(filters: OrderFilters): Promise<Order[]>;
+  search(query: string): Promise<Order[]>;
+}
+```
+
+### Invariants in the Interface
+
+The interface includes not just types, but everything a caller must know:
+
+```typescript
+interface PaymentService {
+  // ❌ Interface hides invariants
+  processPayment(orderId: string, amount: number): Promise<Receipt>;
+  // Caller must discover: amount must match order total, order must be confirmed,
+  // can't process twice, throws if payment gateway is down.
+
+  // ✅ Interface encodes invariants in types
+  processPayment(
+    order: ConfirmedOrder, // type encodes "must be confirmed"
+    payment: PaymentMethod  // type encodes valid methods
+  ): Promise<Result<Receipt, PaymentError>>;
+  // Error mode explicit in return type. Ordering implicit in input types.
+```
+
+## Dependency Categories
+
+The shape of an interface depends on what it depends on.
+
+| Category | Description | Interface Impact |
+|----------|-------------|------------------|
+| **In-process** | Same memory space, no serialization | Can pass rich types, callbacks, streams |
+| **Local-substitutable** | Same interface, different implementations (real vs test) | Seam is real. Interface must hide implementation |
+| **Ports & adapters** | Crosses a real boundary (DB, HTTP, message queue) | Interface must be narrow. Errors are part of the contract |
+| **Mock** | Test-only dependency, no production equivalent | Don't create a seam. Test the real module |
+
+## Common Interface Anti-Patterns
+
+### Leaky Abstraction
+
+```typescript
+// ❌ Interface exposes implementation
+interface UserRepository {
+  query(sql: string, params: any[]): Promise<Row[]>;
+}
+
+// ✅ Interface hides implementation
+interface UserRepository {
+  findByEmail(email: Email): Promise<User | null>;
+  save(user: User): Promise<User>;
+}
+```
+
+### Pass-Through Interface
+
+```typescript
+// ❌ Every method delegates 1:1 to another module
+class OrderService {
+  async findById(id: string) { return this.repo.findById(id); }
+  async save(order: Order) { return this.repo.save(order); }
+  async delete(id: string) { return this.repo.delete(id); }
+}
+// Deletion test: delete OrderService → complexity doesn't reappear.
+// It's a pass-through. Remove it and call repo directly.
+```
+
+### God Interface
+
+```typescript
+// ❌ One module does everything
+interface PlatformService {
+  createUser(...): Promise<User>;
+  sendEmail(...): Promise<void>;
+  processPayment(...): Promise<Receipt>;
+  generateReport(...): Promise<PDF>;
+}
+// No cohesion. Deleting it would reappear complexity, but in unrelated places.
+// Split by domain responsibility instead.
+```
+
+### Chatty Interface
+
+```typescript
+// ❌ Many small methods that must be called in sequence
+interface OrderBuilder {
+  setCustomer(customerId: string): this;
+  addItem(item: OrderItem): this;
+  setShipping(address: Address): this;
+  setPayment(method: PaymentMethod): this;
+  validate(): Result<void>;
+  build(): Order;
+}
+// Callers must know ordering. State machine hidden in method calls.
+// Better: single method that takes a complete request.
+```
+
+## Decision Checklist
+
+Before finalizing an interface:
+
+- [ ] Run the deletion test — does complexity reappear across N callers?
+- [ ] Check depth — is the interface at least 3x smaller than the implementation?
+- [ ] Verify seam — are there at least two adapters?
+- [ ] Encode invariants — are error modes, ordering, and constraints visible in types?
+- [ ] Test surface — can you test all behaviour through the public interface?
+- [ ] Hide details — does the interface leak SQL, HTTP, frameworks, or implementation?
+- [ ] Common case — is the most frequent caller's experience trivial?

package/skills/oracle-doubt/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: oracle-doubt
+description: >
+  Adversarial review of non-trivial decisions using fresh-context scrutiny.
+  Use when correctness matters more than speed, when stakes are high
+  (production, security-sensitive logic, irreversible operations), or before
+  committing significant architectural or implementation choices.
+user-invocable: true
+---
+
+# Doubt: Fresh-Context Adversarial Review
+
+A confident answer is not a correct one. Long sessions accumulate context that quietly turns assumptions into "facts" without anyone noticing. Doubt-driven development is the discipline of materializing a fresh-context reviewer — biased to **disprove**, not approve — before any non-trivial output stands.
+
+This is not `/review`. `/review` is a verdict on a finished artifact. This is an in-flight posture: non-trivial decisions get cross-examined while course-correction is still cheap.
+
+## When to Use
+
+A decision is **non-trivial** when at least one of these is true:
+
+- It introduces or modifies branching logic
+- It crosses a module or service boundary
+- It asserts a property the type system or compiler cannot verify (thread safety, idempotence, ordering, invariants)
+- Its correctness depends on context the future reader cannot see
+- Its blast radius is irreversible (production deploy, data migration, public API change)
+
+Apply the skill when:
+
+- About to make an architectural decision under uncertainty
+- About to commit non-trivial code
+- About to claim a non-obvious fact ("this is safe", "this scales", "this matches the spec")
+- Working in code you don't fully understand
+
+**When NOT to use:**
+
+- Mechanical operations (renaming, formatting, file moves)
+- Following a clear, unambiguous user instruction
+- Reading or summarizing existing code
+- One-line changes with obvious correctness
+- Pure tooling operations (running tests, listing files)
+- The user has explicitly asked for speed over verification
+
+If you doubt every keystroke, you ship nothing. The skill applies only to non-trivial decisions as defined above.
+
+## Loading Constraints
+
+This skill is designed for the **main-session orchestrator**, where Step 3 (DOUBT) can spawn fresh-context reviewers via the `task` tool.
+
+- **Do NOT add this skill to a persona's `skills:` frontmatter.** A persona that follows Step 3 would spawn another persona — the orchestration anti-pattern explicitly forbidden by `references/orchestration-patterns.md` ("personas do not invoke other personas").
+- **If you find yourself applying this skill from inside a subagent context** (where nested subagent spawn is prevented): the preferred path is to surface to the user that doubt-driven cannot run nested and let the main session handle it. As a last resort only, a degraded self-questioning fallback exists — rewrite ARTIFACT + CONTRACT as a fresh self-prompt with a hard mental separator from your prior reasoning, and walk Steps 1–5. This is **not fresh-context review** (you carry your own context with you), so flag the result as degraded and prefer escalation whenever the user is reachable.
+
+## The Process
+
+Copy this checklist when applying the skill:
+
+```
+Doubt cycle:
+- [ ] Step 1: CLAIM — wrote the claim + why-it-matters
+- [ ] Step 2: EXTRACT — isolated artifact + contract, stripped reasoning
+- [ ] Step 3: DOUBT — invoked fresh-context reviewer with adversarial prompt
+- [ ] Step 4: RECONCILE — classified every finding against the artifact text
+- [ ] Step 5: STOP — met stop condition (trivial findings, 3 cycles, or user override)
+```
+
+### Step 1: CLAIM — Surface what stands
+
+Name the decision in two or three lines:
+
+```
+CLAIM: "The new caching layer is thread-safe under the
+        read-heavy workload described in the spec."
+WHY THIS MATTERS: a race here corrupts user data and is
+                  hard to detect in QA.
+```
+
+If you can't write the claim that compactly, you have a vibe, not a decision. Surface it before scrutinizing it.
+
+### Step 2: EXTRACT — Smallest reviewable unit
+
+A fresh-context reviewer needs the **artifact** and the **contract**, not the journey.
+
+- **Code**: the diff or the function — not the whole file
+- **Decision**: the proposal in 3–5 sentences plus the constraints it has to satisfy
+- **Assertion**: the claim plus the evidence that supposedly supports it (kept distinct from the Step 1 CLAIM block, which is the orchestrator's hypothesis under scrutiny)
+
+Strip your reasoning. If you hand over conclusions, you'll get back validation of your conclusions. The unit must be small enough that a reviewer can hold it in mind in one read — if it's a 500-line PR, decompose first.
+
+### Step 3: DOUBT — Invoke the fresh-context reviewer
+
+The reviewer's prompt **must be adversarial**. Framing decides the answer.
+
+Use the adversarial prompt template from [references/adversarial-prompt.md](references/adversarial-prompt.md). The template is pasted verbatim into the subagent invocation to override any persona's default balanced response shape.
+
+**Pass ARTIFACT + CONTRACT only. Do NOT pass the CLAIM.** Handing the reviewer your conclusion biases it toward agreement. The reviewer must independently determine whether the artifact satisfies the contract.
+
+#### Cross-model escalation
+
+A single-model reviewer shares blind spots with the original author — a colder, different-architecture perspective catches them. Doubt-driven is already opt-in for non-trivial decisions, so within that scope offering cross-model is part of the skill's value, not optional friction.
+
+**Interactive sessions: always offer. Never silently skip.**
+
+**Step 1: Ask the user**
+
+After the single-model review in Step 3 above, but before RECONCILE, pause and ask:
+
+> *"Single-model review complete. Want a cross-model second opinion? Options: spawn parallel subagents with different types (oracle + architect), manual external review (you paste it elsewhere), or skip."*
+
+This question is mandatory in every interactive doubt cycle — even on artifacts that feel low-stakes. The user — not the agent — decides whether the cost is worth it. The agent's job is to surface the choice.
+
+**Step 2: If the user picks parallel subagents — dispatch**
+
+Spawn two `task` subagents in parallel with the same adversarial prompt + ARTIFACT + CONTRACT:
+
+```
+task tool:
+  subagent_type: oracle
+task tool:
+  subagent_type: architect
+```
+
+Each subagent starts with isolated context by design. Take both outputs into Step 4 (RECONCILE).
+
+**Step 3: If the user skips**
+
+Acknowledge the skip in the output (*"Proceeding with single-model findings only"*) and continue to RECONCILE. Skipping is fine; silent skipping is not.
+
+**Non-interactive contexts** (CI, scheduled runs):
+
+- Cross-model is **skipped**, and the skip must be **announced** in the output: *"Cross-model skipped: non-interactive context."*
+- **Never invoke external subagents without explicit user authorization** — this is a load-bearing safety property.
+
+Cross-model adds cost, latency, and tool fragility. The agent surfaces the choice every cycle; the user decides whether this artifact warrants it.
+
+### Step 4: RECONCILE — Fold findings back
+
+The reviewer's output is data, not verdict. **You are still the orchestrator.** Re-read the artifact text against each finding before classifying — rubber-stamping the reviewer is the same failure mode as ignoring it.
+
+For each finding, classify in this **precedence order** (first matching class wins):
+
+1. **Contract misread** — reviewer flagged something specifically because the CONTRACT you provided was unclear or incomplete. Fix the contract first, re-classify on the next cycle.
+2. **Valid + actionable** — real issue requiring a change to the artifact. Change it, re-loop.
+3. **Valid trade-off** — issue is real but cost of fixing exceeds cost of accepting. Document the trade-off explicitly so the user sees it.
+4. **Noise** — reviewer flagged something that's actually correct under context the reviewer didn't have. Note it, move on, and ask: would adding that context to the contract have prevented the false flag?
+
+A fresh reviewer can be wrong because it lacks context. Don't defer just because it's "fresh."
+
+### Step 5: STOP — Bounded loop, not recursion
+
+Stop when:
+
+- Next iteration returns only trivial or already-considered findings, **or**
+- 3 cycles completed (escalate to user, don't grind a fourth alone), **or**
+- User explicitly says "ship it"
+
+If after 3 cycles the reviewer still surfaces substantive issues, the artifact may not be ready. Surface this to the user — three unresolved cycles is information about the artifact, not a reason to keep looping.
+
+If 3 cycles is "obviously insufficient" because the artifact is large: the artifact is too big — return to Step 2 and decompose. Do not lift the bound.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'm confident, skip the doubt step" | Confidence correlates poorly with correctness on novel problems. Moments of certainty are exactly when blind spots hide. |
+| "Spawning a reviewer is expensive" | Debugging a wrong commit in production is more expensive. The check is bounded; the bug isn't. |
+| "The reviewer will just nitpick" | Only if unscoped. Constrain the prompt to "issues that would make this fail under the contract." |
+| "I'll do doubt at the end with `/review`" | `/review` is a final gate. Doubt-driven catches wrong directions early when course-correction is cheap. By PR time it's too late. |
+| "If I doubt every step I'll never ship" | The skill applies to non-trivial decisions, not every keystroke. Re-read "When NOT to Use." |
+| "Two opinions are always better than one" | Not when the second has less context and produces noise. Reconcile, don't defer. |
+| "The reviewer disagreed so I was wrong" | The reviewer lacks your context — disagreement is information, not verdict. Re-read the artifact, classify, then decide. |
+| "Cross-model is always better" | Cross-model catches blind spots a single model shares with itself, but it adds cost and tool fragility. Offer it every interactive doubt cycle — the user decides whether the artifact warrants it. The agent's job is to surface the choice, not to gate it. |
+| "User said yes once, so I can keep invoking subagents" | Each invocation is its own authorization. The artifact, the prompt, and the context change between calls — re-confirm with the user before every run. |
+
+## Red Flags
+
+- Spawning a fresh-context reviewer for a one-line rename or formatting change
+- Treating reviewer output as authoritative without re-reading the artifact text
+- Looping >3 cycles without escalating to the user
+- Prompting the reviewer with "is this good?" instead of "find issues"
+- Skipping doubt under time pressure on a high-stakes decision
+- Re-spawning fresh-context on an unchanged artifact (you'll get the same findings; you're stalling)
+- **Doubt theater (checkable signal)**: across 2 or more cycles where the reviewer surfaced substantive findings, zero findings were classified as actionable. You are validating, not doubting. Stop and escalate.
+- Doubting only after committing — that's `/review`, not doubt-driven development
+- Hardcoding a subagent invocation without confirming with the user that the approach is acceptable
+- **Silently skipping cross-model in an interactive doubt cycle.** Even when not recommending it, the offer must be visible. Skipping is fine; silent skipping is not.
+- Falling back silently when a subagent errors or is unavailable — surface the failure and let the user redirect
+- Stripping the contract from the reviewer's input
+- Passing the CLAIM to the reviewer (biases toward agreement)
+
+## Interaction with Other Skills
+
+- **`code-review` / `/review`**: complementary. `/review` is post-hoc PR verdict; doubt-driven is in-flight per-decision. Use both.
+- **`oracle-architect`** / **`spec-research`**: SDD verifies *facts about frameworks* against official docs. Doubt-driven verifies *your reasoning about the artifact*. SDD checks the API exists; doubt-driven checks you used it correctly under the contract.
+- **`oracle-testing`**: TDD's RED step is doubt made concrete — a failing test is a disproof attempt. When TDD applies, that failing test *is* the doubt step for behavioral claims.
+- **`code-debug`**: when the reviewer surfaces a real failure mode, drop into the debugging skill to localize and fix.
+
+## Verification
+
+After applying doubt-driven development:
+
+- Every non-trivial decision (per the definition above) was named explicitly as a CLAIM before standing
+- At least one fresh-context review per non-trivial artifact (a failing test produced by TDD's RED step satisfies this for behavioral claims, per Interaction with Other Skills)
+- The reviewer received ARTIFACT + CONTRACT — NOT the CLAIM, NOT your reasoning
+- The reviewer's prompt was adversarial ("find issues"), not validating ("is it good")
+- Findings were classified against the artifact text (not rubber-stamped) using the precedence: contract misread / actionable / trade-off / noise
+- A stop condition was met (trivial findings, 3 cycles, or user override)
+- In interactive mode, cross-model was **explicitly offered** to the user (regardless of artifact stakes) and the response was acknowledged in the output
+- In non-interactive mode, cross-model was skipped and the skip was announced
+- Any subagent invocation was preceded by user authorization and confirmation of the approach
+
+## Usage Examples
+
+**Doubt an architectural decision:**
+```
+/atelier-doubt
+CLAIM: "I will use DynamoDB single-table design for the Order service."
+WHY: "Single-table simplifies access patterns but may couple unrelated domains."
+ARTIFACT: "Proposed key schema: PK=ORDER#<id>, SK=METADATA#<id>. All order data in one table."
+CONTRACT: "Must support: 1) lookup by order ID, 2) list by customer, 3) list by status. No cross-domain queries."
+```
+
+**Doubt a code change before commit:**
+```
+/atelier-doubt
+CLAIM: "The retry logic in PaymentService is safe under concurrent requests."
+WHY: "Race here could double-charge customers."
+ARTIFACT: "<paste diff or function>"
+CONTRACT: "Must be idempotent: same paymentId processed twice produces same result, no duplicate charges."
+```
+
+**Doubt a non-obvious assertion:**
+```
+/atelier-doubt
+CLAIM: "This migration is safe to run online without downtime."
+WHY: "Downtime here blocks checkout for all users."
+ARTIFACT: "ALTER TABLE orders ADD COLUMN tracking_id VARCHAR(255); CREATE INDEX idx_tracking ON orders(tracking_id);"
+CONTRACT: "Must not lock table for more than 1 second. Must not fail on 10M row table. Must be backward-compatible with running application code."
+```
+
+## Relationship to Other Skills
+
+| Skill | Use When |
+|---|---|
+| **oracle-doubt** | In-flight adversarial review before a decision stands. Catches wrong directions early. |
+| **oracle-challenge** | Critically evaluating an existing approach or decision after it's been made. |
+| **code-review** | Post-hoc PR verdict on a finished artifact. |
+| **oracle-testing** | TDD RED step serves as the doubt mechanism for behavioral claims. |
+| **oracle-thinkdeep** | Deep exploration and alternative discovery for complex decisions (use doubt after thinkdeep narrows to a specific choice). |
+
+**Key distinction:**
+- `oracle-doubt` = "Before I commit to this, prove me wrong" (pre-commit adversarial review)
+- `oracle-challenge` = "Is this approach valid?" (critical evaluation of standing decisions)
+- `code-review` = "Judge this finished artifact" (post-hoc verdict)