codex-genesis-harness 0.1.1 → 0.1.4

package/.codex/skills/genesis-harness/checklists/bug-fix-qa.md

@@ -0,0 +1,169 @@
+# Bug Fix Q&A Checklist
+
+**Purpose**: Structured questionnaire to understand and document bug fixes before planning /fix-bug.
+
+**Status**: MANDATORY - Complete before creating implementation plan.
+
+## Bug Identification & Reproduction
+
+- [ ] **Bug clearly described**:
+  - What is the incorrect behavior?
+  - What should happen instead?
+  - Step-by-step repro steps documented
+
+- [ ] **Reproducibility confirmed**:
+  - Consistently reproducible?
+  - Specific conditions/environment needed?
+  - Affects all users or specific scenarios?
+
+- [ ] **Severity & Priority assessed**:
+  - Critical (blocks core functionality)?
+  - High (significant impact, workaround exists)?
+  - Medium (inconvenience, non-blocking)?
+  - Low (cosmetic, nice-to-fix)?
+
+- [ ] **Affected Versions identified**:
+  - When was this introduced?
+  - Which versions affected?
+  - Latest stable version affected?
+
+## Root Cause Analysis
+
+- [ ] **Root cause identified** (or hypothesis if unknown):
+  - Specific code location/module?
+  - Logic error or incorrect assumption?
+  - Missing validation or error handling?
+  - Race condition or state issue?
+  - Integration bug with external service?
+
+- [ ] **Why was it missed**:
+  - Was there a test that should have caught this?
+  - Missing test coverage?
+  - Environment-specific (dev vs. production)?
+
+- [ ] **Affected systems mapped**:
+  - Single module or cross-module issue?
+  - API side or client side?
+  - Database or state management?
+  - Performance or correctness?
+
+## Impact Assessment
+
+- [ ] **Data Integrity concerns**:
+  - Has data been corrupted or lost?
+  - Rollback/recovery strategy needed?
+  - Data migration required after fix?
+
+- [ ] **User Impact**:
+  - How many users affected?
+  - What functionality is broken?
+  - Workaround available in the meantime?
+
+- [ ] **Breaking Change Risk**:
+  - Does the fix change public API behavior?
+  - Will this break existing clients?
+  - Backward compatibility needed?
+
+## Fix Strategy
+
+- [ ] **Fix approach decided**:
+  - Minimal change to fix only the bug?
+  - Or refactor to prevent similar bugs?
+  - Tradeoffs understood?
+
+- [ ] **Side Effects considered**:
+  - What other code paths use this?
+  - Could this fix introduce new bugs?
+  - Dependencies to check?
+
+- [ ] **Regression Prevention**:
+  - What test catches this bug?
+  - Test added before or after fix?
+  - Similar patterns to look for?
+
+## Testing & Verification
+
+- [ ] **Test Case for Bug**:
+  - Failing test created before fix?
+  - Test reproduces the exact bug?
+  - Test passes after fix?
+
+- [ ] **Regression Tests**:
+  - Existing tests still pass?
+  - Edge cases covered?
+  - Similar bugs tested in other areas?
+
+- [ ] **Verification Plan**:
+  - How will we verify fix in production?
+  - Monitoring/alerts to confirm success?
+  - Rollback plan if fix causes issues?
+
+## Deployment & Release
+
+- [ ] **Hotfix or Regular Release**:
+  - Needs immediate hotfix deployment?
+  - Can wait for next regular release?
+  - Affects which release branches?
+
+- [ ] **Release Notes**:
+  - What message for end users?
+  - Migration steps if needed?
+  - Workaround guidance during transition?
+
+- [ ] **Rollout Strategy**:
+  - Staged rollout or immediate?
+  - Feature flags needed?
+  - Canary deployment approach?
+
+## Documentation Updates
+
+- [ ] **Docs need updating**:
+  - Behavior changed in docs?
+  - Workaround documented?
+  - Migration guide needed?
+
+- [ ] **Release Notes written**:
+  - User-friendly description
+  - Workaround mentioned if applicable
+  - Any breaking changes noted
+
+## Lesson Learned
+
+- [ ] **How to prevent this in future**:
+  - Better test coverage?
+  - Code review checklist item?
+  - Documentation gap?
+  - Process improvement?
+
+- [ ] **Similar bugs searched**:
+  - Pattern scan for similar issues in codebase?
+  - Found and fixed other instances?
+
+---
+
+## Usage
+
+Use this checklist **before** calling `/fix-bug`:
+
+```
+1. Read and reproduce the bug
+2. Complete this checklist thoroughly
+3. Add bug details to implementation plan
+4. Create failing test first
+5. Fix with minimal change
+6. Verify all tests pass
+7. Document lesson learned
+```
+
+## Known Information About Bug
+
+- **Bug ID/Ticket**: _reference_
+- **Reported By**: _name_
+- **Date Reported**: _YYYY-MM-DD_
+- **Current Status**: _New / Assigned / In Progress_
+
+---
+
+**Checklist Completed**: ☐  
+**Date**: _YYYY-MM-DD_  
+**Assigned To**: _Name_

package/.codex/skills/genesis-harness/checklists/new-feature-qa.md

@@ -0,0 +1,157 @@
+# New Feature Q&A Checklist
+
+**Purpose**: Structured questionnaire to capture all requirements before planning /new-feature.
+
+**Status**: MANDATORY - Complete all fields before /plan is created.
+
+## User Story & Intent
+
+- [ ] **User Story defined**: "As a [who], I want [what] so that [why]"
+  - Who is the primary user/actor?
+  - What specific action or capability do they need?
+  - What outcome or value does this deliver?
+
+- [ ] **Success Criteria clear**: How do we know this feature is working?
+  - At least 3 measurable criteria
+  - Business metrics or user satisfaction indicators
+
+- [ ] **Out of Scope documented**: What is explicitly NOT included?
+  - Related features we're NOT doing now
+  - Future enhancements or phases
+
+## Requirements & Constraints
+
+- [ ] **Functional Requirements clear**:
+  - Primary use cases (happy path)
+  - Secondary use cases
+  - Data inputs and outputs
+
+- [ ] **Non-Functional Requirements identified**:
+  - Performance expectations (speed, throughput, latency)
+  - Scalability requirements
+  - Availability/uptime requirements
+  - Browser/device support
+
+- [ ] **Dependencies & Integrations mapped**:
+  - Does this touch APIs? Which ones?
+  - Database schema changes needed?
+  - External services involved?
+  - Existing modules that will be modified?
+
+- [ ] **Constraints & Limitations noted**:
+  - Technical constraints (memory, compute)
+  - Business constraints (timeline, budget)
+  - Regulatory/compliance constraints
+  - Breaking changes or migration requirements?
+
+## Impact & Scope
+
+- [ ] **Affected Systems identified**:
+  - Which modules will change? (list by name)
+  - Which APIs will change or be added?
+  - Which database tables/schemas affected?
+  - Frontend routes or pages added/modified?
+
+- [ ] **API Surface Changes**:
+  - New endpoints needed?
+  - Modified endpoint behavior?
+  - Deprecated endpoints?
+  - Data contract changes?
+
+- [ ] **Database Changes**:
+  - New tables/collections?
+  - Schema migrations?
+  - Backward compatibility concerns?
+
+- [ ] **UI/UX Changes**:
+  - New pages/screens?
+  - Modified navigation flows?
+  - New user interactions?
+
+## Edge Cases & Error Handling
+
+- [ ] **Edge Cases enumerated**:
+  - Boundary conditions (empty, null, max values)
+  - Concurrent operations conflicts
+  - Network failures or timeouts
+  - Permission/authorization scenarios
+  - Race conditions or state inconsistencies
+
+- [ ] **Error Scenarios documented**:
+  - Invalid input handling
+  - Failure recovery strategy
+  - User-facing error messages
+  - Logging/observability for debugging
+
+## Architecture & Design
+
+- [ ] **Architectural Pattern chosen**:
+  - Synchronous vs. asynchronous?
+  - Client-side vs. server-side?
+  - Real-time vs. eventual consistency?
+  - Distributed or monolithic?
+
+- [ ] **Design Decisions recorded** (Why this approach?):
+  - What alternatives were considered?
+  - Why this one was chosen?
+  - Any known tradeoffs?
+
+- [ ] **Performance Considerations**:
+  - Caching strategy if needed?
+  - Query optimization?
+  - Batch processing opportunities?
+
+## Testing Strategy
+
+- [ ] **Test Coverage planned**:
+  - Unit tests (which modules?)
+  - Integration tests (which interactions?)
+  - E2E tests (which user flows?)
+  - Target coverage: 80%+ or higher?
+
+- [ ] **Test Data & Fixtures**:
+  - What test data do we need?
+  - Realistic edge case fixtures?
+  - Performance test datasets?
+
+## Rollout & Monitoring
+
+- [ ] **Deployment Strategy**:
+  - Staged rollout or all-at-once?
+  - Feature flags needed?
+  - Rollback plan if issues arise?
+
+- [ ] **Monitoring & Observability**:
+  - What metrics should we track?
+  - Key logs to monitor?
+  - Alert thresholds?
+
+## Sign-Off
+
+- [ ] **Stakeholder confirmation**: Product owner/PM approved?
+- [ ] **Tech lead review**: Architecture and scope approved?
+- [ ] **No unknowns remaining**: All "TBD" fields resolved?
+
+---
+
+## Usage
+
+Use this checklist **before** calling `/plan` for a new feature:
+
+```
+1. Read this checklist
+2. Answer every question (or explicitly mark "not applicable")
+3. If any field is "TBD" or uncertain, add to "Known Unknowns"
+4. Share answers with /plan command
+5. /plan creates implementation strategy
+```
+
+## Known Unknowns (for this feature)
+
+- [ ] _Add any uncertain items here_
+
+---
+
+**Date**: _YYYY-MM-DD_  
+**Author**: _Name_  
+**Feature**: _[Feature Name]_

package/.codex/skills/genesis-harness/checklists/refactor-qa.md

@@ -0,0 +1,216 @@
+# Refactor Q&A Checklist
+
+**Purpose**: Structured questionnaire for planning code refactors to avoid scope creep and ensure clarity.
+
+**Status**: MANDATORY - Complete before creating refactor plan.
+
+## Refactor Goals & Scope
+
+- [ ] **Primary goal clearly stated**:
+  - Performance improvement? (which metrics?)
+  - Code quality/readability?
+  - Architecture simplification?
+  - Tech debt reduction?
+  - Preparation for new feature?
+  - Remove deprecated code?
+
+- [ ] **Scope boundaries defined**:
+  - Exactly which modules/files are in scope?
+  - What is explicitly NOT being refactored?
+  - Why these boundaries?
+
+- [ ] **Success Criteria measurable**:
+  - Performance: specific metrics (latency, memory, throughput)?
+  - Quality: complexity reduction targets?
+  - Lines of code reduction targets?
+  - Test coverage maintained/improved?
+
+## Impact Assessment
+
+- [ ] **Risk Level assessed**:
+  - Low risk (isolated, well-tested)?
+  - Medium risk (touches multiple areas)?
+  - High risk (core/critical system)?
+
+- [ ] **Affected Systems identified**:
+  - Which modules/components use this code?
+  - Public APIs that might change?
+  - Dependent code that needs updates?
+  - Cross-team dependencies?
+
+- [ ] **Breaking Changes evaluated**:
+  - Does this change public API?
+  - Will clients need updates?
+  - Backward compatibility strategy?
+  - Deprecation path if needed?
+
+- [ ] **Data/State Concerns**:
+  - Does this handle state/persistence?
+  - Migration strategy if data format changes?
+  - Existing data compatibility?
+
+## Technical Approach
+
+- [ ] **Refactor Strategy decided**:
+  - Big bang replacement or incremental?
+  - Parallel implementation then cut over?
+  - Feature flag strategy?
+  - Gradual migration approach?
+
+- [ ] **Alternatives considered**:
+  - Why this approach over others?
+  - Tradeoffs understood?
+  - Reversibility of changes?
+
+- [ ] **Dependencies researched**:
+  - Library/framework upgrades needed?
+  - New patterns or tools to learn?
+  - Compatibility concerns?
+
+## Testing & Verification
+
+- [ ] **Test Coverage analyzed**:
+  - Current coverage percentage?
+  - Coverage targets after refactor?
+  - Tests to add during refactor?
+
+- [ ] **Regression Testing planned**:
+  - Which tests must pass?
+  - Integration test scenarios?
+  - Performance benchmarks to run?
+  - Smoke tests for quick validation?
+
+- [ ] **Manual Testing scenarios**:
+  - Key user flows to validate?
+  - Edge cases to verify?
+  - Environment-specific tests (prod-like)?
+
+## Performance & Quality Metrics
+
+- [ ] **Current metrics captured**:
+  - Baseline performance measured?
+  - Code quality metrics (complexity, duplication)?
+  - Build time benchmarks?
+
+- [ ] **Target metrics defined**:
+  - Expected performance improvement %?
+  - Complexity reduction targets?
+  - Build time targets?
+
+- [ ] **Monitoring plan**:
+  - How will we track post-refactor metrics?
+  - Alerts for regressions?
+  - A/B testing if applicable?
+
+## Timeline & Effort
+
+- [ ] **Effort estimated**:
+  - Estimated hours/days?
+  - Complexity assessment?
+  - Blocking dependencies?
+
+- [ ] **Schedule considered**:
+  - Can this be done incrementally?
+  - Best time in release cycle?
+  - Sprint capacity available?
+
+- [ ] **Rollback plan**:
+  - How long to rollback if needed?
+  - Can we run A/B test?
+  - Version compatibility concerns?
+
+## Stakeholder Alignment
+
+- [ ] **Team consensus**:
+  - Tech lead approved?
+  - Code owners agree this is needed?
+  - Architecture team aligned?
+
+- [ ] **Priority confirmed**:
+  - Product owner informed?
+  - This won't block feature work?
+  - Business case documented?
+
+- [ ] **Knowledge sharing**:
+  - Team trained on new patterns?
+  - Documentation updated?
+  - Code review guidelines updated?
+
+## Documentation & Communication
+
+- [ ] **Refactor Plan documented**:
+  - Current state architecture?
+  - Target state architecture?
+  - Migration path clearly described?
+
+- [ ] **Design Decision recorded**:
+  - ADR created explaining refactor?
+  - Links to discussions/research?
+  - Why-decisions documented?
+
+- [ ] **Communication plan**:
+  - Stakeholders notified?
+  - Progress updates planned?
+  - Release notes prepared?
+
+## Code Quality Standards
+
+- [ ] **Code Quality Checklist**:
+  - Follows team conventions?
+  - No hardcoded values?
+  - Proper error handling?
+  - Comprehensive logging?
+  - Immutable patterns used?
+
+- [ ] **Security considerations**:
+  - No security regressions?
+  - Secrets handling correct?
+  - Access control maintained?
+
+- [ ] **Performance considerations**:
+  - Efficiency improvements realized?
+  - No performance regressions?
+  - Caching used appropriately?
+
+---
+
+## Usage
+
+Use this checklist **before** calling `/plan refactor`:
+
+```
+1. Read this checklist completely
+2. Answer all questions
+3. Get stakeholder alignment on scope
+4. Capture current metrics
+5. Define success criteria
+6. Create implementation plan
+7. Execute incrementally with verification
+```
+
+## Pre-Refactor Checklist
+
+Before starting actual refactoring:
+- [ ] All tests passing in current state?
+- [ ] Current metrics captured/documented?
+- [ ] Feature branch created?
+- [ ] Notification sent to team?
+- [ ] Rollback plan documented and tested?
+
+## Refactor Type
+
+Choose one:
+- [ ] Performance optimization
+- [ ] Code quality improvement
+- [ ] Architecture simplification
+- [ ] Tech debt reduction
+- [ ] Pattern standardization
+- [ ] Library/framework upgrade
+- [ ] Other: _specify_
+
+---
+
+**Checklist Completed**: ☐  
+**Date**: _YYYY-MM-DD_  
+**Lead**: _Name_  
+**Reviewers**: _Names_