safeword 0.2.4 → 0.2.6

package/.safeword/guides/tdd-best-practices.md

@@ -1,570 +0,0 @@
-# TDD Best Practices
-
-Patterns and examples for user stories and test definitions following TDD best practices.
-
-**LLM Instruction Design:** These templates create documentation that LLMs read and follow. For comprehensive framework on writing clear, actionable LLM-consumable documentation, see `@.safeword/guides/llm-instruction-design.md`.
-
----
-
-## Fillable Template Files (When to Use Each)
-
-### Quick Reference
-
-| Need | Template | Location |
-|------|----------|----------|
-| Feature/issue user stories | `user-stories-template.md` | `.safeword/planning/user-stories/` |
-| Feature test suites | `test-definitions-feature.md` | `.safeword/planning/test-definitions/` |
-| Feature implementation design | `design-doc-template.md` | `.safeword/planning/design/` |
-| Project-wide architecture | No template | `ARCHITECTURE.md` at root |
-
-**Decision rule:** If unclear, ask: "Does this affect the whole project or just one feature?" Project-wide → architecture doc. Single feature → design doc.
-
-### Template Details
-
-**User Stories** (`@.safeword/templates/user-stories-template.md`) - **For features/issues**
-- Multiple related stories in one file
-- Status tracking (✅/❌ per story and AC)
-- Test file references and implementation notes
-- Completion % and phase tracking
-- Use for GitHub issues with multiple user stories
-- Guidance: `@.safeword/guides/user-story-guide.md`
-
-**Test Definitions** (`@.safeword/templates/test-definitions-feature.md`) - **For feature test suites**
-- Organized by test suites and individual tests
-- Status tracking (✅ Passing / ⏭️ Skipped / ❌ Not Implemented / 🔴 Failing)
-- Detailed steps and expected outcomes
-- Coverage summary with percentages
-- Test execution commands
-- Guidance: `@.safeword/guides/test-definitions-guide.md`
-
-**Design Doc** (`@.safeword/templates/design-doc-template.md`) - **For feature/system implementation**
-- Implementation-focused (architecture, components, data model, user flow, component interaction)
-- Key technical decisions with rationale (includes "why")
-- Full [N] and [N+1] examples (matches user stories/test definitions pattern)
-- ~121 lines, optimized for LLM filling and consumption
-- No duplication (references user stories, test definitions)
-- Guidance: `@.safeword/guides/architecture-guide.md`
-
-**Architecture Document** (no template) - **For project/package-wide architecture decisions**
-- One `ARCHITECTURE.md` per project or package (in monorepos)
-- Document principles, data model, component design, decision rationale
-- Living document (updated as architecture evolves)
-- Include version, status, table of contents
-- All architectural decisions in one place (not separate ADRs)
-- Guidance: `@.safeword/guides/architecture-guide.md`
-
-**Example prompts:**
-- "Create user stories for issue #N" → Uses user stories template
-- "Create test definitions for issue #N" → Uses test definitions template
-- "Create a design doc for [feature]" → Uses design doc template (2-3 pages)
-- "Update the project architecture doc" → Adds to existing ARCHITECTURE.md
-
-**TDD Workflow:** See `@.safeword/guides/testing-methodology.md` for comprehensive RED → GREEN → REFACTOR workflow with latest best practices
-
----
-
-## User Story Templates
-
-### When to Use Each Format
-
-| Format | Best For | Example Trigger |
-|--------|----------|-----------------|
-| Standard (As a/I want/So that) | User-facing features, UI flows | "User can do X" |
-| Given-When-Then | API behavior, state transitions, edge cases | "When X happens, then Y" |
-| Job Story | Problem-solving, user motivation unclear | "User needs to accomplish X" |
-
-**Decision rule:** Default to Standard. Use Given-When-Then for APIs or complex state. Use Job Story when focusing on the problem, not the solution.
-
-### Standard Format (Recommended)
-
-```
-As a [role/persona]
-I want [capability/feature]
-So that [business value/benefit]
-
-Acceptance Criteria:
-- [Specific, testable condition 1]
-- [Specific, testable condition 2]
-- [Specific, testable condition 3]
-
-Out of Scope:
-- [What this story explicitly does NOT include]
-```
-
-### Given-When-Then Format (Behavior-Focused)
-
-```
-Given [initial context/state]
-When [action/event occurs]
-Then [expected outcome]
-
-And [additional context/outcome]
-But [exception/edge case]
-```
-
-**Filled example:**
-```
-Given I am an authenticated API user
-When I POST to /api/campaigns with valid JSON
-Then I receive a 201 Created response with campaign ID
-And the campaign appears in my GET /api/campaigns list
-But invalid JSON returns 400 with descriptive error messages
-```
-
-### Job Story Format (Outcome-Focused)
-
-```
-When [situation/context]
-I want to [motivation/job-to-be-done]
-So I can [expected outcome]
-```
-
-**Filled example:**
-```
-When I'm debugging a failing test
-I want to see the exact LLM prompt and response
-So I can identify whether the issue is prompt engineering or code logic
-```
-
----
-
-## User Story Best Practices
-
-### ✅ GOOD Examples
-
-**Web App Feature:**
-```
-As a user with multiple campaigns
-I want to switch between campaigns without reloading the page
-So that I can quickly compare game states
-
-Acceptance Criteria:
-- Campaign list shows all saved campaigns with last-played timestamp
-- Clicking a campaign loads its state within 200ms
-- Current campaign is visually highlighted
-- Switching preserves unsaved input in the current campaign
-
-Out of Scope:
-- Campaign merging/deletion (separate story)
-- Multi-campaign view (future epic)
-```
-
-**API Feature:**
-```
-Given I am an authenticated API user
-When I POST to /api/campaigns with valid JSON
-Then I receive a 201 Created response with campaign ID
-And the campaign appears in my GET /api/campaigns list
-But invalid JSON returns 400 with descriptive error messages
-```
-
-**CLI Feature:**
-```
-When I'm debugging a failing test
-I want to see the exact LLM prompt and response
-So I can identify whether the issue is prompt engineering or code logic
-
-Acceptance Criteria:
-- `--verbose` flag prints full prompt to stderr
-- Response JSON is pretty-printed with syntax highlighting
-- Token count and cost are displayed
-- Works with all agent types (rules, narrative, character)
-```
-
-**With Technical Constraints:**
-```
-As a user with multiple campaigns
-I want to switch between campaigns without reloading the page
-So that I can quickly compare game states
-
-Acceptance Criteria:
-- Campaign list shows all saved campaigns with last-played timestamp
-- Clicking a campaign loads its state within 200ms
-- Current campaign is visually highlighted
-
-Technical Constraints:
-Performance:
-- [ ] Campaign switch completes in < 200ms at P95
-- [ ] Works with up to 50 campaigns without UI lag
-
-Compatibility:
-- [ ] Chrome 100+, Safari 16+, Firefox 115+
-
-Data:
-- [ ] Campaign data persists across browser sessions
-```
-
-### ❌ BAD Examples (Anti-Patterns)
-
-**Too Vague:**
-```
-As a user
-I want the app to work better
-So that I'm happy
-```
-- ❌ No specific role
-- ❌ "Work better" is not measurable
-- ❌ No acceptance criteria
-
-**Too Technical (Implementation Details):**
-```
-As a developer
-I want to refactor the CharacterStore to use Immer
-So that state mutations are prevented
-```
-- ❌ This is a technical task, not a user story
-- ❌ Users don't care about Immer
-- ✅ Better as: Spike ticket or refactoring task
-
-**Missing "So That" (No Value):**
-```
-As a GM
-I want to roll dice
-```
-- ❌ No business value stated
-- ❌ Why does the GM need this?
-
-**Multiple Features in One Story:**
-```
-As a player
-I want to create characters, manage inventory, and track relationships
-So that I can play the game
-```
-- ❌ 3+ separate features bundled together
-- ❌ Cannot be completed in one sprint
-- ✅ Split into 3 stories
-
----
-
-## Test Definition Templates
-
-### Unit Test Template
-
-```typescript
-describe('[Unit/Module Name]', () => {
-  describe('[function/method name]', () => {
-    it('should [expected behavior] when [condition]', () => {
-      // Arrange: Set up test data and dependencies
-      const input = { /* test data */ };
-      const expected = { /* expected output */ };
-
-      // Act: Execute the function under test
-      const result = functionUnderTest(input);
-
-      // Assert: Verify the outcome
-      expect(result).toEqual(expected);
-    });
-
-    it('should throw [error type] when [invalid condition]', () => {
-      const invalidInput = { /* bad data */ };
-
-      expect(() => functionUnderTest(invalidInput))
-        .toThrow('Expected error message');
-    });
-
-    it('should handle edge case: [specific edge case]', () => {
-      // Edge cases: empty arrays, null, undefined, boundary values
-    });
-  });
-});
-```
-
-### Integration Test Template
-
-```typescript
-describe('[Feature Name] Integration', () => {
-  beforeEach(async () => {
-    // Setup: Initialize database, mock external APIs
-    await setupTestDatabase();
-  });
-
-  afterEach(async () => {
-    // Teardown: Clean up resources
-    await cleanupTestDatabase();
-  });
-
-  it('should [complete user flow] successfully', async () => {
-    // Arrange: Create test user and prerequisites
-    const user = await createTestUser();
-
-    // Act: Execute the full workflow
-    const campaign = await createCampaign(user.id);
-    const character = await createCharacter(campaign.id);
-    const result = await performAction(character.id, 'Skirmish');
-
-    // Assert: Verify end-to-end behavior
-    expect(result.position).toBe('risky');
-    expect(result.effect).toBe('standard');
-    expect(campaign.history).toHaveLength(1);
-  });
-
-  it('should rollback transaction when [failure occurs]', async () => {
-    // Test error handling and data consistency
-  });
-
-  // Filled example: rollback on failure
-  it('should rollback order when payment fails', async () => {
-    const user = await createTestUser();
-    const order = await createOrder(user.id, { items: ['sword'] });
-    
-    // Simulate payment failure
-    mockPaymentGateway.mockRejectedValue(new Error('Card declined'));
-    
-    await expect(processOrder(order.id)).rejects.toThrow('Card declined');
-    
-    // Verify rollback - order cancelled, inventory restored
-    const updatedOrder = await getOrder(order.id);
-    expect(updatedOrder.status).toBe('cancelled');
-    expect(await getInventory('sword')).toBe(1); // Not decremented
-  });
-});
-```
-
-### E2E Test Template (Playwright/Cypress)
-
-```typescript
-test.describe('[User Journey Name]', () => {
-  test('should [complete full user flow]', async ({ page }) => {
-    // Arrange: Navigate to starting point
-    await page.goto('/campaigns');
-
-    // Act: Simulate user interactions
-    await page.click('button:has-text("New Campaign")');
-    await page.fill('[name="campaignName"]', 'The Bloodletters');
-    await page.click('button:has-text("Create")');
-
-    // Assert: Verify UI state matches expectations
-    await expect(page.locator('h1')).toContainText('The Bloodletters');
-    await expect(page.locator('.campaign-list')).toContainText('The Bloodletters');
-
-    // Act: Continue the flow
-    await page.click('button:has-text("Create Character")');
-
-    // Assert: Verify next state
-    await expect(page).toHaveURL(/\/characters\/create/);
-  });
-});
-```
-
----
-
-## Test Best Practices
-
-### Test Naming Conventions
-
-**✅ GOOD - Descriptive and Specific:**
-```typescript
-it('should return risky position when outnumbered 3-to-1')
-it('should cache LLM responses for 5 minutes to reduce costs')
-it('should preserve armor state after reducing harm from L2 to L1')
-it('should throw ValidationError when dice pool is negative')
-```
-
-**❌ BAD - Vague or Implementation-Focused:**
-```typescript
-it('works correctly')  // What does "correctly" mean?
-it('tests the function')  // Obvious, not descriptive
-it('should call setState')  // Implementation detail
-it('scenario 1')  // No context
-```
-
-**How to rename:**
-1. Identify the behavior being tested
-2. Identify the condition/input
-3. Use pattern: `'should [behavior] when [condition]'`
-
-Example: `'works correctly'` → `'should return 200 when user is authenticated'`
-
-### Arrange-Act-Assert (AAA) Pattern
-
-**Always use AAA structure for clarity:**
-
-```typescript
-it('should calculate critical success on 6', () => {
-  // Arrange: Setup test data
-  const diceResults = [6, 6, 4];
-
-  // Act: Execute the logic
-  const outcome = evaluateDiceRoll(diceResults);
-
-  // Assert: Verify expectations
-  expect(outcome).toBe('critical');
-  expect(outcome.highestDie).toBe(6);
-});
-```
-
-### Test Independence
-
-**✅ GOOD - Isolated Tests:**
-```typescript
-beforeEach(() => {
-  // Each test gets fresh state
-  gameState = createFreshGameState();
-});
-
-it('test A', () => { /* uses gameState */ });
-it('test B', () => { /* uses separate gameState */ });
-```
-
-**❌ BAD - Shared State:**
-```typescript
-let sharedState = {}; // Tests modify this
-it('test A', () => { sharedState.foo = 'bar'; });
-it('test B', () => { expect(sharedState.foo).toBe('bar'); }); // Depends on test A!
-```
-
-### What to Test
-
-**✅ Test These:**
-- Public API behavior (functions, methods, components)
-- User-facing features (can the user do X?)
-- Edge cases (empty, null, boundary values)
-- Error handling (does it fail gracefully?)
-- Integration points (API calls, database queries)
-
-**❌ Don't Test These:**
-- Private implementation details (internal helper functions)
-- Third-party library internals (assume React works)
-- Generated code (unless it's business logic)
-- Trivial getters/setters with no logic
-
-**Boundary example:**
-```typescript
-// ❌ DON'T test this private helper
-function _formatDateInternal(date) { /* internal logic */ }
-
-// ✅ DO test the public function that uses it
-export function getFormattedTimestamp(event) {
-  return _formatDateInternal(event.createdAt);
-}
-// Test getFormattedTimestamp, not _formatDateInternal
-```
-
-### Test Data Builders
-
-**Use builders for complex test data:**
-
-```typescript
-// ✅ GOOD - Reusable test data builder
-function buildCharacter(overrides = {}) {
-  return {
-    id: 'test-char-1',
-    name: 'Cutter',
-    playbook: 'Cutter',
-    stress: 0,
-    harm: [],
-    armor: true,
-    ...overrides  // Easy to customize per test
-  };
-}
-
-it('should increase stress when resisting', () => {
-  const character = buildCharacter({ stress: 3 });
-  // Test uses character with stress=3
-});
-```
-
----
-
-## LLM Testing Patterns
-
-### Promptfoo LLM-as-Judge Template
-
-```yaml
-# Tests for AI outputs (narrative quality, reasoning)
-prompts:
-  - file://prompts/gm-narrative.txt
-
-providers:
-  - id: anthropic:messages:claude-sonnet-4
-    config:
-      temperature: 1.0
-
-tests:
-  - description: "GM should telegraph position/effect before roll"
-    vars:
-      action: "I Skirmish with the gang enforcers"
-      character: { /* character JSON */ }
-    assert:
-      - type: llm-rubric
-        value: |
-          The GM response must:
-          - State position (controlled/risky/desperate) explicitly
-          - State effect (limited/standard/great) explicitly
-          - Explain WHY these were chosen based on fiction
-
-          Grade as:
-          EXCELLENT: All three present and clear
-          ACCEPTABLE: Position and effect stated, reasoning weak
-          POOR: Missing position or effect
-
-      - type: llm-rubric
-        value: |
-          Does the GM show collaborative tone (asking questions, inviting detail)?
-
-          EXCELLENT: Asks open-ended questions, invites player creativity
-          ACCEPTABLE: Acknowledges player action, minimal collaboration
-          POOR: Dictates outcomes without player input
-```
-
-### Integration Test with Real LLM
-
-```typescript
-describe('Rules Agent Integration', () => {
-  it('should infer correct position for desperate situation', async () => {
-    // Arrange
-    const scenario = {
-      action: 'I Skirmish against 5 armed guards while wounded',
-      character: buildCharacter({ harm: [{ level: 2, description: 'Broken Arm' }] })
-    };
-
-    // Act: Real LLM call (costs ~$0.01)
-    const response = await rulesAgent.processAction(scenario);
-
-    // Assert: Structured output (not narrative quality)
-    expect(response.position).toBe('desperate');
-    expect(response.effect).toBe('limited');
-    expect(response.dicePool).toBeLessThan(3); // Harm reduces dice
-    expect(response.consequences).toContain('severe harm');
-  });
-});
-```
-
----
-
-## INVEST Checklist (Apply to Every User Story)
-
-Before writing a story, verify it passes all six criteria:
-
-- [ ] **Independent** - Can be completed without depending on other stories
-- [ ] **Negotiable** - Details emerge through conversation, not a fixed contract
-- [ ] **Valuable** - Delivers clear value to user or business
-- [ ] **Estimable** - Team can estimate effort (not too vague, not too detailed)
-- [ ] **Small** - Completable in one sprint/iteration (typically 1-5 days)
-- [ ] **Testable** - Clear acceptance criteria define when it's done
-
-**If a story fails any criteria, it's not ready - refine or split it.**
-
----
-
-## Quick Reference
-
-**User Story Red Flags (INVEST Violations):**
-- No acceptance criteria → Too vague
-- >3 acceptance criteria → Split into multiple stories
-- Technical implementation details → Wrong audience
-- Missing "So that" → No clear value
-
-**Test Red Flags:**
-- Test name doesn't describe behavior → Rename
-- Test depends on another test's state → Isolate
-- Test is >50 lines → Break into smaller tests
-- Test tests implementation details → Test behavior instead
-- Test never fails → Remove (not testing anything)
-
-**When to Write E2E vs Integration vs Unit:**
-- **E2E:** User can complete full workflow (slow, expensive, high confidence)
-- **Integration:** Multiple modules work together (moderate speed, good ROI)
-- **Unit:** Single function/module logic (fast, cheap, low-level confidence)
-
-**Ratio guidance:** 70% unit, 20% integration, 10% E2E (adjust based on project)