chati-dev 1.3.3 → 2.0.1

package/framework/tasks/dev-debug.md

@@ -0,0 +1,322 @@
+---
+id: dev-debug
+agent: dev
+trigger: dev-refactor
+phase: build
+requires_input: false
+parallelizable: false
+outputs: [debug-log]
+handoff_to: dev-code-review
+autonomous_gate: true
+criteria:
+  - All tests passing
+  - No runtime errors
+---
+# Debug and Fix
+
+## Purpose
+Identify and resolve any failing tests, runtime errors, or unexpected behaviors discovered during or after refactoring.
+
+## Prerequisites
+- Refactoring complete
+- Test suite available
+- Refactor report exists
+- Source maps configured
+- Debugging tools available
+
+## Steps
+
+### 1. Run Full Test Suite
+Execute all tests to identify failures:
+```bash
+npm test
+```
+- Record which tests fail
+- Note error messages
+- Identify patterns in failures
+- Check for flaky tests
+- Document success rate
+
+### 2. Analyze Test Failures
+Understand why tests are failing:
+- Read error messages carefully
+- Check stack traces
+- Identify failed assertions
+- Review test expectations
+- Compare expected vs actual output
+
+### 3. Reproduce Issues Locally
+Isolate failing tests:
+```bash
+npm test -- --testNamePattern="specific test"
+```
+- Run individual tests
+- Add console.log for debugging
+- Use debugger breakpoints
+- Inspect intermediate values
+- Verify test setup
+
+### 4. Check Recent Changes
+Review what changed:
+- Compare with last working state
+- Check refactoring changes
+- Review type changes
+- Inspect renamed functions
+- Verify imports updated
+
+### 5. Add Diagnostic Logging
+Insert strategic log statements:
+```typescript
+console.log('Input:', JSON.stringify(input, null, 2));
+console.log('Processing step 1 complete');
+console.log('Output:', JSON.stringify(output, null, 2));
+```
+- Log function entry/exit
+- Log intermediate values
+- Log conditional branches taken
+- Log error conditions
+- Remove logs after debugging
+
+### 6. Use Interactive Debugger
+For complex issues, use debugger:
+- Set breakpoints in IDE
+- Step through execution
+- Inspect variable values
+- Watch expressions
+- Examine call stack
+
+### 7. Fix Root Causes
+Address underlying issues:
+- Fix logic errors
+- Correct type mismatches
+- Update broken references
+- Repair data flow
+- Resolve timing issues
+
+Common fixes:
+```typescript
+// Fix async handling
+await someAsyncFunction(); // Don't forget await
+
+// Fix null checks
+if (value !== null && value !== undefined) { }
+
+// Fix type assertions
+const typed = value as ExpectedType;
+
+// Fix array operations
+const items = array.filter(item => item !== null);
+```
+
+### 8. Fix Flaky Tests
+Address intermittent failures:
+- Identify timing dependencies
+- Add proper waits/delays
+- Mock time-dependent functions
+- Ensure proper cleanup
+- Reset state between tests
+
+### 9. Update Tests if Needed
+Sometimes tests need fixing, not code:
+- Check if expectations are still valid
+- Update mocks if interfaces changed
+- Fix test setup
+- Adjust assertions
+- Update test data
+
+### 10. Verify Fixes
+Confirm issues resolved:
+- Run failing test multiple times
+- Run full suite
+- Check for new failures
+- Verify coverage maintained
+- Test in different scenarios
+
+### 11. Test Runtime Scenarios
+Beyond unit tests, verify runtime behavior:
+- Start the application
+- Exercise the new feature
+- Check console for errors
+- Verify expected behavior
+- Test error cases manually
+
+### 12. Document Debugging Process
+Record issues and solutions:
+- List bugs found
+- Note root causes
+- Document fixes applied
+- Record lessons learned
+- Update tests or code comments
+
+## Decision Points
+
+### When Root Cause is Unclear
+If you can't identify the problem:
+1. Add more logging
+2. Simplify the test case
+3. Remove complexity incrementally
+4. Compare with working code
+5. Ask for user input if stuck
+
+### When Fix Would Be Major
+If fix requires significant changes:
+1. Document the issue
+2. Assess impact
+3. Propose solution to user
+4. May need to revisit architecture
+5. Don't make large changes without approval
+
+### When Tests Need Updating
+Determine if test or code is wrong:
+1. Review acceptance criteria
+2. Check if behavior intentionally changed
+3. Verify test assumptions
+4. Update test if refactor changed behavior correctly
+5. Fix code if behavior is wrong
+
+## Error Handling
+
+### Cannot Reproduce Failure
+- Check test isolation
+- Verify environment setup
+- Clear caches and rebuild
+- Check for timing issues
+- Run tests multiple times
+
+### Debugger Not Working
+- Verify source maps configured
+- Check IDE debugger setup
+- Use console.log as fallback
+- Ensure breakpoints in executed code
+- Check for minification issues
+
+### Cascading Failures
+When one fix breaks other tests:
+- Run tests after each fix
+- Commit working states
+- Use git to track changes
+- Fix issues incrementally
+- Consider reverting and retrying
+
+### Performance Issues
+If debugging reveals performance problems:
+- Profile the code
+- Identify bottlenecks
+- Note for optimization later
+- Don't optimize prematurely
+- Document performance concerns
+
+## Output Format
+
+Create `.chati/artifacts/build/debug-log.yaml`:
+
+```yaml
+task_id: "3.2.1"
+agent: dev
+action: debug
+timestamp: "2026-02-13T12:45:00Z"
+duration_minutes: 30
+
+initial_test_status:
+  total_tests: 20
+  passing: 17
+  failing: 3
+  flaky: 0
+
+failures_identified:
+  - test: "ChatService should emit message event on send"
+    file: "chat-service.test.ts"
+    error: "Expected emit to be called with 'message', but was not called"
+    category: logic_error
+  - test: "should sanitize HTML in messages"
+    file: "chat-service.test.ts"
+    error: "TypeError: sanitizeHtml is not a function"
+    category: refactor_issue
+  - test: "Integration: WebSocket receives new messages"
+    file: "chat-integration.test.ts"
+    error: "Timeout: async callback not invoked within 5000ms"
+    category: async_issue
+
+debugging_steps:
+  - issue: "Missing emit call"
+    approach: "Added logging to trace execution flow"
+    finding: "Event emission code removed during refactoring"
+    fix: "Re-added this.emit('message', message) call"
+  - issue: "sanitizeHtml not a function"
+    approach: "Checked imports after refactoring"
+    finding: "Import statement not updated when function moved"
+    fix: "Updated import to reference new validators.ts module"
+  - issue: "WebSocket timeout"
+    approach: "Used debugger to step through async flow"
+    finding: "Promise never resolved due to missing await"
+    fix: "Added await to async WebSocket send call"
+
+fixes_applied:
+  - file: "src/modules/chat/chat-service.ts"
+    change: "Re-added event emission after message save"
+    lines_changed: 2
+  - file: "src/modules/chat/chat-service.ts"
+    change: "Fixed import path for sanitizeHtml"
+    lines_changed: 1
+  - file: "src/modules/chat/chat-service.ts"
+    change: "Added await to WebSocket broadcast"
+    lines_changed: 1
+
+tests_updated:
+  - file: "chat-service.test.ts"
+    change: "Updated mock setup for new module structure"
+    reason: "Test assumptions outdated after refactoring"
+  - file: "chat-integration.test.ts"
+    change: "Increased timeout to 10000ms for WebSocket test"
+    reason: "Integration test needs more time in CI environment"
+
+runtime_verification:
+  - scenario: "Send message via API"
+    result: success
+    notes: "Message persisted and broadcast correctly"
+  - scenario: "Send message with HTML"
+    result: success
+    notes: "HTML properly sanitized"
+  - scenario: "Send empty message"
+    result: success
+    notes: "Validation error thrown as expected"
+
+final_test_status:
+  total_tests: 20
+  passing: 20
+  failing: 0
+  flaky: 0
+  coverage: 89.2
+
+lessons_learned:
+  - "Always update imports when moving functions during refactoring"
+  - "Verify async operations have proper await keywords"
+  - "Test event emission explicitly, don't assume it works"
+  - "Integration tests may need longer timeouts in CI"
+
+remaining_issues:
+  - description: "WebSocket test still occasionally times out"
+    severity: low
+    status: monitoring
+    plan: "May need to mock WebSocket in tests"
+
+code_quality_after_fixes:
+  lint_status: pass
+  type_check_status: pass
+  compilation_status: pass
+  test_status: pass
+
+next_steps:
+  - "Perform self code review"
+  - "Check against architecture and standards"
+  - "Prepare for PR"
+```
+
+## Success Criteria
+- All tests pass consistently
+- No runtime errors when exercising features
+- Code compiles without errors
+- Type checking passes
+- Linting passes
+- Debug log documents all issues found and fixed
+- No known bugs remain

package/framework/tasks/dev-implement.md

@@ -0,0 +1,252 @@
+---
+id: dev-implement
+agent: dev
+trigger: orchestrator
+phase: build
+requires_input: false
+parallelizable: true
+outputs: [source-code]
+handoff_to: dev-test-write
+autonomous_gate: true
+criteria:
+  - Code compiles without errors
+  - All acceptance criteria implemented
+  - No lint errors
+---
+# Implement Feature
+
+## Purpose
+Transform acceptance criteria from the task specification into working source code, following the project's architecture and coding standards.
+
+## Prerequisites
+- Task specification exists in `.chati/state/current-task.yaml`
+- Architecture decisions documented in `.chati/artifacts/architecture/`
+- Development environment configured
+- Dependencies installed
+- IDE ready with proper extensions
+
+## Steps
+
+### 1. Load Task Context
+Read the current task specification to understand:
+- Acceptance criteria (Given-When-Then format)
+- Affected components
+- Data models
+- API contracts
+- UI requirements
+
+### 2. Review Architecture Constraints
+Examine architecture artifacts to ensure compliance with:
+- Folder structure conventions
+- Module boundaries
+- Design patterns in use
+- Technology stack choices
+- State management approach
+
+### 3. Identify Existing Patterns
+Search the codebase for similar implementations:
+- Use Grep to find comparable features
+- Analyze existing component structure
+- Identify reusable utilities
+- Note naming conventions
+- Review error handling patterns
+
+### 4. Plan Implementation Approach
+Create a mental model of:
+- Which files need creation vs modification
+- Component hierarchy
+- Data flow
+- Side effects and state changes
+- Integration points
+
+### 5. Implement Core Logic
+Write the primary functionality:
+- Start with data layer (models, schemas, types)
+- Implement business logic (services, utilities)
+- Add API endpoints or handlers
+- Follow single responsibility principle
+- Keep functions focused and testable
+
+### 6. Implement User-Facing Layer
+Add presentation or interface components:
+- UI components (if applicable)
+- CLI commands (if applicable)
+- API response formatting
+- Validation and sanitization
+- User feedback mechanisms
+
+### 7. Add Error Handling
+Implement comprehensive error management:
+- Try-catch blocks around risky operations
+- Meaningful error messages
+- Proper error propagation
+- Fallback behaviors
+- Logging for debugging
+
+### 8. Add Type Safety
+Ensure full type coverage:
+- TypeScript interfaces for all data structures
+- Type guards where needed
+- Avoid `any` types
+- Use generics appropriately
+- Document complex types
+
+### 9. Add Documentation
+Document the implementation:
+- JSDoc comments for public APIs
+- Inline comments for complex logic
+- README updates if needed
+- Code examples in comments
+- Architecture decision records
+
+### 10. Verify Compilation
+Check that code compiles:
+- Run `npm run build` or equivalent
+- Fix any TypeScript errors
+- Resolve import issues
+- Check for unused variables
+- Validate syntax
+
+### 11. Run Linting
+Ensure code style compliance:
+- Run `npm run lint`
+- Fix any style violations
+- Apply auto-fixes where safe
+- Verify naming conventions
+- Check formatting
+
+### 12. Create Implementation Log
+Document what was built:
+- List files created
+- List files modified
+- Note design decisions
+- Record any deviations from spec
+- Flag items needing review
+
+## Decision Points
+
+### When Architecture is Unclear
+If the architecture doesn't specify how to implement something:
+1. Document the ambiguity
+2. Propose 2-3 approaches
+3. Use AskUserQuestion tool
+4. Record decision in `.chati/artifacts/decisions/`
+
+### When Dependencies are Missing
+If required libraries aren't available:
+1. Check package.json for alternatives
+2. Propose dependency additions
+3. Get user approval before installing
+4. Document dependency purpose
+
+### When Spec is Ambiguous
+If acceptance criteria are unclear:
+1. Implement the most reasonable interpretation
+2. Add TODO comments marking assumptions
+3. Flag for QA review
+4. Document in implementation log
+
+## Error Handling
+
+### Compilation Errors
+- Read error messages carefully
+- Check import paths
+- Verify type definitions exist
+- Ensure all dependencies installed
+- Review tsconfig.json settings
+
+### Lint Failures
+- Apply auto-fix first: `npm run lint -- --fix`
+- Review remaining errors manually
+- Check for unused variables
+- Verify naming conventions
+- Fix formatting issues
+
+### Integration Issues
+- Verify API contracts match
+- Check data flow assumptions
+- Test integration points manually
+- Add logging to trace data
+- Review component boundaries
+
+### Performance Concerns
+- Profile critical paths if needed
+- Avoid premature optimization
+- Document performance decisions
+- Flag expensive operations
+- Consider lazy loading
+
+## Output Format
+
+Create `.chati/artifacts/build/implementation-log.yaml`:
+
+```yaml
+task_id: "3.2.1"
+agent: dev
+action: implement
+timestamp: "2026-02-13T10:30:00Z"
+duration_minutes: 45
+
+files_created:
+  - path: "src/modules/chat/chat-service.ts"
+    lines: 156
+    purpose: "Core chat message handling"
+  - path: "src/modules/chat/types.ts"
+    lines: 42
+    purpose: "Chat domain types"
+
+files_modified:
+  - path: "src/index.ts"
+    changes: "Added chat module export"
+    lines_added: 3
+  - path: "src/types/global.d.ts"
+    changes: "Extended global chat types"
+    lines_added: 12
+
+acceptance_criteria_met:
+  - id: "AC-1"
+    description: "Chat messages persist to database"
+    status: implemented
+  - id: "AC-2"
+    description: "Real-time updates via WebSocket"
+    status: implemented
+  - id: "AC-3"
+    description: "Message validation and sanitization"
+    status: implemented
+
+design_decisions:
+  - decision: "Used EventEmitter for message broadcasting"
+    rationale: "Simpler than Redux for this use case"
+    alternatives_considered: ["Redux", "MobX"]
+  - decision: "SQLite for message storage"
+    rationale: "Lightweight, embedded, sufficient for MVP"
+    alternatives_considered: ["PostgreSQL", "MongoDB"]
+
+deviations_from_spec:
+  - description: "Added message edit capability"
+    reason: "User feedback indicated this was critical"
+    approved_by: "user"
+
+technical_debt:
+  - description: "Message pagination not optimized"
+    impact: "May slow with 1000+ messages"
+    planned_fix: "Implement virtual scrolling in Phase 4"
+
+compilation_status: success
+lint_status: success
+type_check_status: success
+
+next_steps:
+  - "Write tests for chat-service.ts"
+  - "Add integration tests for WebSocket flow"
+  - "Document chat API in README"
+```
+
+## Success Criteria
+- All code compiles without errors
+- All lint checks pass
+- All acceptance criteria have corresponding implementation
+- Implementation log is complete and accurate
+- Code follows project conventions
+- Error handling is comprehensive
+- Types are fully specified