@martinffx/atelier 1.2.2 → 1.3.0

package/skills/oracle-testing/references/stub-driven-tdd.md

@@ -1,322 +0,0 @@
-# Stub-Driven TDD Workflow
-
-Complete workflow examples showing the Stub → Test → Implement → Refactor pattern.
-
-## The Four-Step Pattern
-
-```
-1. Stub   → Create minimal interface/function signatures
-2. Test   → Write tests against stubs
-3. Implement → Make tests pass with real implementation
-4. Refactor  → Improve code while keeping tests green
-```
-
-## Why Stub-Driven?
-
-**Traditional TDD problem:** Can't write tests until implementation exists
-
-**Stub-Driven solution:** Write interface/type signatures first, test against those, then implement
-
-**Benefits:**
-- Tests define behavior before implementation
-- Interfaces emerge from use cases, not speculation
-- Refactoring is safe (tests validate behavior)
-- Fast feedback loop (stub → test → implement)
-
-## Complete Order Service Example
-
-### Step 1: Stub
-
-Define the interface and service class with stub methods:
-
-```typescript
-// Define repository interface from use case
-interface OrderRepository {
-  save(order: OrderRecord): Promise<OrderRecord>;
-  findById(id: string): Promise<OrderRecord | null>;
-  delete(id: string): Promise<void>;
-}
-
-// Service uses stub - methods throw NotImplemented
-class OrderService {
-  constructor(private repo: OrderRepository) {}
-
-  async createOrder(request: CreateOrderRequest): Promise<Result<Order>> {
-    throw new Error('Not implemented');
-  }
-
-  async cancelOrder(id: string): Promise<Result<void>> {
-    throw new Error('Not implemented');
-  }
-
-  async getOrder(id: string): Promise<Result<Order>> {
-    throw new Error('Not implemented');
-  }
-}
-
-// Export for testing
-export { OrderService, OrderRepository };
-```
-
-### Step 2: Test
-
-Write comprehensive tests against the stubs:
-
-```typescript
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { OrderService, OrderRepository } from './order-service';
-import { CreateOrderRequest, OrderRecord, Order } from './order';
-import { Ok, Err } from './result';
-
-describe('OrderService', () => {
-  let service: OrderService;
-  let mockRepo: OrderRepository;
-
-  beforeEach(() => {
-    // Create stub implementation
-    mockRepo = {
-      save: vi.fn(),
-      findById: vi.fn(),
-      delete: vi.fn()
-    };
-    service = new OrderService(mockRepo);
-  });
-
-  describe('createOrder', () => {
-    it('should save valid order', async () => {
-      mockRepo.save.mockResolvedValue({
-        id: '123',
-        customer_id: 'C1',
-        items: '[]',
-        status: 'pending',
-        total: 0
-      });
-
-      const result = await service.createOrder({
-        customerId: 'C1',
-        items: [{ productId: 'P1', quantity: 2, price: 10 }]
-      });
-
-      expect(result.ok).toBe(true);
-      expect(mockRepo.save).toHaveBeenCalledWith(
-        expect.objectContaining({
-          customer_id: 'C1',
-          status: 'pending'
-        })
-      );
-    });
-
-    it('should validate order before saving', async () => {
-      const result = await service.createOrder({
-        customerId: 'C1',
-        items: [] // Invalid: empty items
-      });
-
-      expect(result.ok).toBe(false);
-      expect(mockRepo.save).not.toHaveBeenCalled();
-    });
-
-    it('should calculate total correctly', async () => {
-      mockRepo.save.mockResolvedValue({
-        id: '123',
-        customer_id: 'C1',
-        items: '[]',
-        status: 'pending',
-        total: 0
-      });
-
-      await service.createOrder({
-        customerId: 'C1',
-        items: [
-          { productId: 'P1', quantity: 2, price: 10 },
-          { productId: 'P2', quantity: 1, price: 15 }
-        ]
-      });
-
-      expect(mockRepo.save).toHaveBeenCalledWith(
-        expect.objectContaining({ total: 35 })
-      );
-    });
-  });
-
-  describe('cancelOrder', () => {
-    it('should cancel pending order', async () => {
-      mockRepo.findById.mockResolvedValue({
-        id: '123',
-        customer_id: 'C1',
-        items: '[]',
-        status: 'pending',
-        total: 0
-      });
-      mockRepo.delete.mockResolvedValue(undefined);
-
-      const result = await service.cancelOrder('123');
-
-      expect(result.ok).toBe(true);
-      expect(mockRepo.delete).toHaveBeenCalledWith('123');
-    });
-
-    it('should reject canceling shipped order', async () => {
-      mockRepo.findById.mockResolvedValue({
-        id: '123',
-        customer_id: 'C1',
-        items: '[]',
-        status: 'shipped',
-        total: 0
-      });
-
-      const result = await service.cancelOrder('123');
-
-      expect(result.ok).toBe(false);
-      expect(mockRepo.delete).not.toHaveBeenCalled();
-    });
-
-    it('should reject canceling non-existent order', async () => {
-      mockRepo.findById.mockResolvedValue(null);
-
-      const result = await service.cancelOrder('999');
-
-      expect(result.ok).toBe(false);
-    });
-  });
-
-  describe('getOrder', () => {
-    it('should retrieve order by id', async () => {
-      mockRepo.findById.mockResolvedValue({
-        id: '123',
-        customer_id: 'C1',
-        items: '[]',
-        status: 'pending',
-        total: 0
-      });
-
-      const result = await service.getOrder('123');
-
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value.id).toBe('123');
-      }
-    });
-
-    it('should return error for non-existent order', async () => {
-      mockRepo.findById.mockResolvedValue(null);
-
-      const result = await service.getOrder('999');
-
-      expect(result.ok).toBe(false);
-    });
-  });
-});
-```
-
-### Step 3: Implement
-
-Make tests pass with real implementation:
-
-```typescript
-class OrderService {
-  constructor(private repo: OrderRepository) {}
-
-  async createOrder(request: CreateOrderRequest): Promise<Result<Order>> {
-    // Transform request to entity
-    const order = Order.fromRequest(request);
-
-    // Validate
-    const validation = order.validate();
-    if (!validation.ok) return validation;
-
-    // Save to repository
-    const record = order.toRecord();
-    const saved = await this.repo.save(record);
-
-    // Transform back to entity
-    return Ok(Order.fromRecord(saved));
-  }
-
-  async cancelOrder(id: string): Promise<Result<void>> {
-    // Find order
-    const record = await this.repo.findById(id);
-    if (!record) return Err('Order not found');
-
-    // Transform to entity
-    const order = Order.fromRecord(record);
-
-    // Check business rule
-    if (!order.canCancel()) {
-      return Err(`Cannot cancel ${order.status} order`);
-    }
-
-    // Delete
-    await this.repo.delete(id);
-    return Ok(undefined);
-  }
-
-  async getOrder(id: string): Promise<Result<Order>> {
-    // Find order
-    const record = await this.repo.findById(id);
-    if (!record) return Err('Order not found');
-
-    // Transform to entity
-    return Ok(Order.fromRecord(record));
-  }
-}
-```
-
-### Step 4: Refactor
-
-Improve code while keeping tests green:
-
-```typescript
-class OrderService {
-  constructor(private repo: OrderRepository) {}
-
-  async createOrder(request: CreateOrderRequest): Promise<Result<Order>> {
-    const order = Order.fromRequest(request);
-    return await this.validateAndSave(order);
-  }
-
-  async cancelOrder(id: string): Promise<Result<void>> {
-    const order = await this.findOrderOrError(id);
-    if (!order.ok) return order;
-
-    return await this.checkCancellableAndDelete(order.value);
-  }
-
-  async getOrder(id: string): Promise<Result<Order>> {
-    return await this.findOrderOrError(id);
-  }
-
-  private async validateAndSave(order: Order): Promise<Result<Order>> {
-    const validation = order.validate();
-    if (!validation.ok) return validation;
-
-    const record = order.toRecord();
-    const saved = await this.repo.save(record);
-    return Ok(Order.fromRecord(saved));
-  }
-
-  private async findOrderOrError(id: string): Promise<Result<Order>> {
-    const record = await this.repo.findById(id);
-    if (!record) return Err('Order not found');
-    return Ok(Order.fromRecord(record));
-  }
-
-  private async checkCancellableAndDelete(order: Order): Promise<Result<void>> {
-    if (!order.canCancel()) {
-      return Err(`Cannot cancel ${order.status} order`);
-    }
-    await this.repo.delete(order.id);
-    return Ok(undefined);
-  }
-}
-```
-
-All tests still pass after refactoring - behavior is unchanged, only implementation improved.
-
-## Key Takeaways
-
-1. **Start with stubs** - Define interfaces before implementation
-2. **Test against contracts** - Test the interface, not the implementation
-3. **Implement once tests are clear** - Make tests pass with real code
-4. **Refactor with confidence** - Tests validate behavior doesn't change
-5. **Keep feedback loop fast** - Each step is quick and focused

package/skills/oracle-thinkdeep/SKILL.md

@@ -1,164 +0,0 @@
----
-name: oracle-thinkdeep
-description: Extended reasoning analysis using sequential thinking. Use for deep exploration, comprehensive analysis, complex decisions, or when you need fresh perspectives on difficult problems.
-user-invocable: true
----
-
-# ThinkDeep: Extended Reasoning Analysis
-
-## Step 1: Parse Request Parameters
-
-<strategist>
-@agent-oracle
-
-Analyze the thinkdeep request: $ARGUMENTS
-
-**Parameter Extraction:**
-- **Main prompt**: [extract core thinking request]
-- **Focus areas**: [extract "architecture, performance, security" etc]
-- **File references**: [extract "reference to file.py" patterns]
-- **Problem context**: [extract additional context provided]
-
-**Parsed Configuration:**
-- Prompt: [core request]
-- Focus areas: [identified areas]
-- File references: [any files mentioned]
-- Problem context: [additional context]
-</strategist>
-
-## Step 2: Deep Sequential Analysis
-
-<strategist>
-@agent-oracle
-
-Use sequential thinking (mcp__sequential-thinking__sequentialthinking) for extended reasoning:
-
-### Thought 1: Context Understanding
-Analyze the current session context to understand:
-- What has been discussed so far
-- Previous decisions and analyses made
-- User's specific constraints and goals
-- Existing solutions or approaches tried
-
-### Thought 2: Problem Decomposition
-Break down the core issue into:
-- Primary problem statement
-- Key sub-problems or components
-- Underlying assumptions and constraints
-- Success criteria and desired outcomes
-
-### Thought 3: Assumption Challenge
-Question the underlying assumptions:
-- What assumptions are we making?
-- Are these assumptions valid in this context?
-- What if the opposite were true?
-- Alternative perspectives to consider
-
-### Thought 4: Alternative Approaches Exploration
-Explore different solution paths:
-- Conventional approaches and their pros/cons
-- Unconventional or innovative solutions
-- Trade-offs between different options
-- Hybrid or combined approaches
-
-### Thought 5: Context Integration
-Incorporate relevant context:
-- File references and code patterns
-- Previous session insights
-- User's specific technical stack
-- Business or project constraints
-
-### Thought 6: Edge Case Analysis
-Identify potential issues:
-- What could go wrong with each approach?
-- Edge cases and failure modes
-- Scalability and performance concerns
-- Security and maintenance implications
-
-### Thought 7: Risk Assessment
-Evaluate risks for each option:
-- Implementation complexity
-- Technical debt potential
-- Team skill requirements
-- Timeline and resource impacts
-
-### Thought 8: Solution Synthesis
-Combine insights into recommendations:
-- Primary recommended approach
-- Backup or alternative options
-- Implementation considerations
-- Next steps and validation points
-
-Continue sequential thinking until satisfaction, using:
-- `isRevision: true` to refine previous thoughts
-- `branchFromThought` to explore alternative reasoning paths
-- `needsMoreThoughts: true` to extend analysis if needed
-</strategist>
-
-## Step 3: Critical Evaluation & Synthesis
-
-**Self-Critique Questions:**
-- Does the analysis address the user's specific context?
-- Are the recommendations practical and implementable?
-- Have we considered the most important constraints?
-- Are there any blind spots or missing perspectives?
-
-**Contextual Validation:**
-- Fit with user's technical stack and preferences
-- Alignment with previous decisions in session
-- Practicality given team skills and resources
-- Integration with existing systems or patterns
-
-**Final Synthesis:**
-- **Primary Recommendation**: [best approach with rationale]
-- **Alternative Options**: [backup plans with trade-offs]
-- **Implementation Guidance**: [key considerations and next steps]
-- **Risk Mitigation**: [how to address identified concerns]
-
----
-
-## Usage Examples
-
-**Basic deep analysis:**
-```
-/atelier-thinkdeep "Analyze my authentication architecture"
-```
-
-**With file references:**
-```
-/atelier-thinkdeep "Evaluate my database schema with reference to models/user.py"
-```
-
-**With focus areas:**
-```
-/atelier-thinkdeep "Assess my microservices design focusing on performance and security"
-```
-
-**Complex architectural decisions:**
-```
-/atelier-thinkdeep "Should I use GraphQL or REST for my API considering team skills and scalability needs"
-```
-
-## When to Use ThinkDeep
-
-- **Architecture decisions**: When choosing between major design approaches
-- **Complex problem solving**: Multi-faceted issues requiring deep analysis
-- **Assumption validation**: Challenging conventional wisdom or previous decisions
-- **Alternative exploration**: When stuck and need fresh perspectives
-- **Risk assessment**: Before major implementation decisions
-
-## ThinkDeep vs Challenge
-
-**Use /atelier-thinkdeep**: Deep exploration, comprehensive analysis, alternative discovery, complex decisions
-**Use /atelier-challenge**: Question assumptions, test validity, assess risks, prevent automatic agreement
-
-**Key distinction**: ThinkDeep = deep exploration, Challenge = critical evaluation
-
-## Expected Outcomes
-
-After using this command:
-- Comprehensive understanding of the problem space
-- Multiple approaches evaluated with trade-offs
-- Clear recommendation with solid reasoning
-- Risk assessment and mitigation strategies
-- Actionable next steps for implementation