kinemotion 0.29.2__tar.gz → 0.30.0__tar.gz

kinemotion-0.30.0/.basic-memory/project-management/kinemotion-project-setup-complete.md

@@ -0,0 +1,149 @@
+---
+title: Kinemotion Project Setup Complete
+type: note
+permalink: project-management/kinemotion-project-setup-complete
+tags:
+- project-management
+- github
+- setup
+- roadmap
+---
+
+# Kinemotion GitHub Project Setup - Complete
+
+## Overview
+Comprehensive GitHub project structure created for Kinemotion with 12 foundation issues, 25 labels, and 3 milestones.
+
+**Project URL**: https://github.com/users/feniix/projects/2
+**Repository**: https://github.com/feniix/kinemotion
+
+## What Was Created
+
+### 12 Foundation Issues
+Organized by domain and milestone, with clear acceptance criteria and specialist agent assignments.
+
+**Testing & Quality (Q1 2025: Core Stability)**
+1. Test Coverage: Drop Jump Edge Cases - 3 SP, qa-test-engineer
+2. Test Coverage: CMJ Edge Cases - 5 SP, qa-test-engineer + cv-engineer
+3. Metrics Validation: Establish Physiological Bounds - 5 SP, biomechanics-specialist
+4. Reduce Code Duplication to <2.5% - 5 SP, python-backend-developer
+
+**Documentation & Education (Q1 2025: Documentation)**
+5. Create CMJ Biomechanics Guide - 3 SP, technical-writer + biomechanics-specialist
+6. Create API Reference & Quick Start - 3 SP, technical-writer + backend-dev
+7. Create Contribution Guidelines & Testing Patterns - 3 SP, technical-writer + qa-engineer
+
+**Technical Improvements (Q2 2025: Performance)**
+8. Improve Pose Detection: Occlusion Handling - 5 SP, cv-engineer + biomechanics
+9. Optimize Video Processing Pipeline - 8 SP, backend-dev + ml-scientist
+10. Expand CI/CD: Automated Quality Gates - 5 SP, devops-engineer
+
+**Future Enhancements (Q2 2025: Performance)**
+11. Feature: Real-time Analysis Streaming - 13 SP, backend-dev + cv-engineer
+12. Improve Batch Processing & Worker Management - 5 SP, python-backend-developer
+
+**Total Effort**: 62 SP across 4 sprints
+**Distribution**: 7 High Priority, 3 Medium Priority, 2 Low Priority
+
+### 25 GitHub Labels
+- **Type Labels** (7): test, feature, refactor, docs, enhancement, perf, ci-cd
+- **Priority Labels** (4): critical, high, medium, low
+- **Scope Labels** (14): testing, drop-jump, cmj, metrics, pose-detection, performance, code-quality, education, api, development, automation, streaming, batch-processing
+
+### 3 Milestones (Pre-existing)
+- **Q1 2025: Core Stability** - Testing, validation, code quality
+- **Q1 2025: Documentation & Education** - User and developer guides
+- **Q2 2025: Performance & Optimization** - Performance, features, infrastructure
+
+## Recommended Sprint Schedule
+
+**Sprint 1 (Q1 Start) - 16 SP**
+- CMJ Edge Cases (5 SP)
+- CMJ Biomechanics Guide (3 SP)
+- Metrics Validation (5 SP)
+- Team: qa-test-engineer, technical-writer, biomechanics-specialist
+
+**Sprint 2 (Q1) - 14 SP**
+- Drop Jump Edge Cases (3 SP)
+- API Reference & Quick Start (3 SP)
+- Contribution Guidelines (3 SP)
+- Code Duplication Reduction (5 SP)
+- Team: qa-engineer, technical-writer, backend-developer
+
+**Sprint 3 (Q2 Start) - 18 SP**
+- Video Processing Optimization (8 SP)
+- Pose Detection Occlusion (5 SP)
+- CI/CD Quality Gates (5 SP)
+- Team: backend-developer, cv-engineer, devops-engineer
+
+**Sprint 4+ (Q2) - 18 SP**
+- Real-time Streaming (13 SP) - May span 2 sprints
+- Batch Processing (5 SP)
+- Team: backend-developer, cv-engineer
+
+## Quality Metrics Tracked
+
+| Metric | Current | Target | Gap |
+|--------|---------|--------|-----|
+| Test Coverage | 74.27% | ≥74% | None |
+| Code Duplication | 2.96% | <2.5% | 0.46% |
+| CMJ Coverage | 62.27% | ≥70% | 7.73% |
+| Drop Jump Coverage | 88.75% | Maintain | None |
+| Type Errors | 0 | 0 | None |
+| Linting Errors | 0 | 0 | None |
+
+Key focus: CMJ edge cases (Issue #2) will increase coverage from 62.27% to 70%.
+
+## Specialist Agent Routing
+
+All issues have explicit agent assignments based on domain expertise:
+- **qa-test-engineer**: Testing, edge cases, fixtures
+- **biomechanics-specialist**: Metrics, validation, physiological bounds
+- **technical-writer**: Documentation, guides, API reference
+- **computer-vision-engineer**: Pose detection, video I/O
+- **python-backend-developer**: Algorithms, optimization, API design
+- **ml-data-scientist**: Parameter tuning, quality presets
+- **devops-cicd-engineer**: CI/CD infrastructure, automation
+
+See `specialist-agents-routing.md` for detailed routing guide.
+
+## Next Steps
+
+1. **Review Issues** - Verify acceptance criteria and adjust estimates
+2. **Assign Team** - Assign issues to available team members
+3. **Sprint Planning** - Plan Sprint 1 (CMJ edge cases, biomechanics guide, metrics validation)
+4. **Kickoff** - Team briefing and task breakdown
+5. **Track Progress** - Use GitHub project board, update status weekly
+
+## Access Points
+
+- **GitHub Project**: https://github.com/users/feniix/projects/2
+- **All Issues**: https://github.com/feniix/kinemotion/issues
+- **By Milestone**: Filter in project board
+- **By Priority**: Search with `label:priority:high`
+- **By Domain**: Search with `label:scope:cmj` or `label:scope:testing`
+
+## Documentation
+
+Memory files created for future reference:
+- `project_overview.md` - Architecture, tech stack, dependencies
+- `suggested_commands.md` - Development workflows and commands
+- `code_style_and_conventions.md` - Type hints, naming, docstrings, patterns
+- `specialist-agents-routing.md` - Agent capabilities and routing guide
+- `github-project-setup-summary.md` - Detailed setup and planning information
+
+## Success Indicators
+
+Project setup complete when:
+- [ ] All 12 issues visible in GitHub project
+- [ ] Labels applied to all issues
+- [ ] Milestones assigned
+- [ ] Team members assigned to Sprint 1 issues
+- [ ] First sprint kickoff completed
+- [ ] CI/CD integrations working (SonarQube, GitHub Actions)
+
+---
+
+**Created**: 2025-11-26
+**Status**: Foundation Complete, Ready for Sprint Planning
+**Next Review**: After Sprint 1 kickoff

kinemotion-0.30.0/.basic-memory/strategy/mvp-feedback-collection-plan.md

@@ -0,0 +1,101 @@
+---
+title: MVP Feedback Collection Plan
+type: note
+permalink: strategy/mvp-feedback-collection-plan
+tags:
+- strategy
+- mvp
+- feedback
+- coaches
+- validation
+---
+
+# MVP Feedback Collection Plan
+
+**Reference:** `docs/strategy/MVP_FEEDBACK_COLLECTION.md` (full detailed version)
+
+**Timeline:** Week 4-5
+**Target:** 5-10 coaches
+**Goal:** Structured feedback to inform Phase 2 decisions
+
+---
+
+## Coach Recruitment
+
+**Target Profile:**
+- Jump sport background (CrossFit, track & field, basketball)
+- Works with athletes
+- Uses video for feedback
+- Willing to spend 15 minutes testing
+
+**Where to Find:**
+- LinkedIn search: "CrossFit coach", "track & field coach"
+- Local CrossFit boxes
+- University programs
+- Reddit communities
+
+---
+
+## 5 Key Questions
+
+1. **Accuracy Trust**
+   - "Do the metrics seem accurate for your athletes?"
+
+2. **Current Workflow**
+   - "How do you currently analyze jump videos?"
+
+3. **Feature Priority** (CRITICAL)
+   - Rate: Real-time vs Running vs API vs UI improvements
+
+4. **Willingness to Pay**
+   - Free only? $50/mo? $100-200/mo? $500+/mo?
+
+5. **Open Feedback**
+   - "What else should we build?"
+
+---
+
+## Feedback Synthesis
+
+After collecting, synthesize:
+- Feature request frequency
+- Willingness to pay distribution
+- Top 3 asks
+- **Recommendation:** Which Phase 2 option won
+
+---
+
+## Week-by-Week Schedule
+
+**Week 4 (Days 1-3):** Recruitment
+- Identify coaches
+- Send outreach emails
+- Confirm 5-10 participants
+
+**Week 4 (Days 4-5):** Early feedback
+- First coaches test MVP
+- Track usage metrics
+- Conduct informal interviews
+
+**Week 5 (Days 1-3):** Full testing
+- Remaining coaches test
+- Conduct formal interviews
+- Collect survey responses
+
+**Week 5 (Days 4-5):** Synthesis & decision
+- Compile feedback
+- Make Phase 2 decision
+
+---
+
+## Success Indicator
+
+MVP feedback collection succeeds when:
+- 5+ coaches tested
+- Clear consensus on Phase 2 priority
+- Evidence supporting recommendation
+- 3+ coaches willing to test Phase 2
+
+---
+
+**See:** `docs/strategy/MVP_FEEDBACK_COLLECTION.md` for complete coaching outreach template and interview script

kinemotion-0.30.0/.basic-memory/strategy/mvp-first-strategic-direction.md

@@ -0,0 +1,103 @@
+---
+title: MVP-First Strategic Direction
+type: note
+permalink: strategy/mvp-first-strategic-direction
+tags:
+- strategy
+- mvp
+- roadmap
+- pivot
+- product-direction
+---
+
+# MVP-First Strategic Direction
+
+**Status:** ACTIVE - Adopted November 26, 2025
+
+**Change:** Pivoted from 6-month comprehensive platform roadmap to 3-week MVP-first validation approach.
+
+---
+
+## Why This Matters
+
+The original strategic roadmap (#10-14) planned to build real-time, running analysis, and API integrations in parallel over 6-8 weeks. **Risk:** You might build features customers don't want.
+
+**New approach:** Ship MVP in 3 weeks, gather customer feedback, then decide Phase 2 based on what they actually ask for.
+
+---
+
+## Phase 1: MVP Validation (Weeks 1-3)
+
+**Three Issues Only:**
+- Issue #10 (P0): Fix CMJ ankle angle calculation
+- Issue #11 (P0): Validate CMJ metrics with phase progression tests
+- Issue #12 (P0): Build simple web UI MVP (upload → analyze → export)
+
+**Goal:** Get product in coaches' hands to gather real feedback
+
+**Resources:** 1-2 developers, 3 weeks
+
+---
+
+## Phase 2: Market-Driven Development (Week 4+)
+
+**Features unblock ONLY if customers request them:**
+
+1. **Real-Time Analysis** - IF 3+ coaches ask for live feedback
+2. **Running Gait Analysis** - IF 3+ coaches/runners ask for it
+3. **API & Integrations** - IF 2+ partners ask for API access
+
+**See:** `MVP_VALIDATION_CHECKPOINTS.md` for explicit unblock criteria
+
+---
+
+## Key Documents
+
+- **Strategic Summary:** `docs/strategy/1-STRATEGIC_SUMMARY.md`
+- **Strategic Analysis:** `docs/strategy/2-STRATEGIC_ANALYSIS.md` (market research, still valid)
+- **MVP Validation Gates:** `docs/strategy/MVP_VALIDATION_CHECKPOINTS.md`
+- **Feedback Collection:** `docs/strategy/MVP_FEEDBACK_COLLECTION.md`
+
+---
+
+## Success Criteria
+
+**Phase 1 Success (Week 3):**
+- Accurate, validated CMJ metrics
+- Simple web UI deployed and live
+- Ready for coach testing
+
+**Phase 2 Decision (Week 4-5):**
+- 5-10 coaches using MVP
+- Clear market feedback on priorities
+- Data to drive Phase 2 decisions
+
+---
+
+## GitHub Issues Status
+
+| Issue | Priority | Phase | Status |
+|-------|----------|-------|--------|
+| #10 | P0 | Phase 1 | MVP - Fix ankle angle |
+| #11 | P0 | Phase 1 | MVP - Validate metrics |
+| #12 | P0 | Phase 1 | MVP - Web UI |
+| #13 | P2 | Phase 2 | DEFERRED - Unblock if requested |
+| #14 | P2 | Phase 2 | DEFERRED - Unblock if requested |
+
+---
+
+## Why MVP-First Is Better
+
+| Aspect | Traditional | MVP-First |
+|--------|-----------|-----------|
+| Timeline | 6-8 weeks | 3 weeks |
+| Dev Cost | 4-5 developers | 1-2 developers |
+| Risk | Build wrong features | Learn before investing |
+| Feedback | After launch | Week 4 |
+| Flexibility | Hard to pivot | Easy to adjust Phase 2 |
+
+---
+
+**Decision Date:** November 26, 2025
+**Updated By:** Project Strategic Pivot
+**Next Review:** After Week 3 MVP launch

kinemotion-0.30.0/.basic-memory/strategy/mvp-validation-checkpoints.md

@@ -0,0 +1,77 @@
+---
+title: MVP Validation Checkpoints
+type: note
+permalink: strategy/mvp-validation-checkpoints
+tags:
+- strategy
+- mvp
+- validation
+- checkpoints
+- decision-gates
+---
+
+# MVP Validation Checkpoints & Phase 2 Decision Gates
+
+**Reference:** `docs/strategy/MVP_VALIDATION_CHECKPOINTS.md` (full detailed version)
+
+**Purpose:** Track MVP progress and define explicit criteria for Phase 2 feature activation
+
+---
+
+## Checkpoint 1: Week 3 (MVP Shipped)
+
+**Go/No-Go Criteria:**
+- [ ] Issue #10 complete: Ankle angle fix validated on real video
+- [ ] Issue #11 complete: Phase progression tests passing
+- [ ] Issue #12 complete: Web UI deployed and publicly accessible
+- [ ] Backend responds without errors
+- [ ] Frontend displays metrics and exports results
+- [ ] Documentation ready for coaches
+
+**Decision:** Go to Checkpoint 2 or fix blockers
+
+---
+
+## Checkpoint 2: Week 4-5 (Market Validation)
+
+**Activities:**
+- [ ] Recruit 5-10 coaches to test MVP
+- [ ] Collect structured feedback (5 key questions)
+- [ ] Track: Feature requests, pain points, willingness to pay
+- [ ] Monitor MVP stability
+
+**Output:** Feedback data from 5-10 coaches
+
+---
+
+## Decision Gate 1: Phase 2 Feature Priority (End Week 5)
+
+### Option A: Real-Time Analysis
+**Unblock if:** 3+ coaches say "I need live feedback"
+- Timeline: 3-4 weeks
+- ROI: 3.2 (market differentiator)
+
+### Option B: Running Gait Analysis
+**Unblock if:** 3+ coaches/runners ask for it
+- Timeline: 2-3 weeks
+- ROI: 3.2 (10x market TAM)
+
+### Option C: API & Integrations
+**Unblock if:** 2+ integration partners request API
+- Timeline: 2 weeks
+- ROI: 4.5 (partnership revenue)
+
+### Option D: Iterate on MVP
+**Unblock if:** MVP liked but needs UX improvements
+- Timeline: 1-2 weeks
+- ROI: Ensures MVP success before expansion
+
+---
+
+## Key Success Metrics
+
+✓ MVP Phase Success = 5+ coaches tested + clear feedback consensus + actionable Phase 2 direction
+
+---
+
+**See:** `docs/strategy/MVP_VALIDATION_CHECKPOINTS.md` for complete decision framework

kinemotion-0.30.0/.serena/memories/code_style_and_conventions.md

@@ -0,0 +1,126 @@
+# Code Style & Conventions for Kinemotion
+
+## Type Hints
+
+- **Required**: All functions must have type hints (Pyright strict mode)
+- **Use**: TypedDict for structured data, type aliases for clarity, NDArray\[dtype\] for NumPy
+- **Pattern**: Function signatures include parameter and return type hints
+  ```python
+  def calculate_jump_height(flight_time: float, gravity: float = 9.81) -> float:
+      """Calculate jump height from flight time."""
+      return gravity * (flight_time / 2) ** 2
+  ```
+
+## Naming Conventions
+
+- **Functions/Variables**: snake_case (e.g., `process_video`, `contact_time`)
+- **Classes**: PascalCase (e.g., `DropJumpAnalyzer`, `CMJPhaseDetector`)
+- **Constants**: UPPER_SNAKE_CASE (e.g., `DEFAULT_QUALITY_PRESET`, `GRAVITY_CONSTANT`)
+- **Private**: Prefix with underscore (e.g., `_internal_helper`)
+
+## Docstrings
+
+- **Format**: Google-style docstrings
+- **Include**: Description, Args, Returns, Raises sections
+  ```python
+  def detect_takeoff(poses: NDArray) -> tuple[int, float]:
+      """Detect takeoff frame and velocity from pose sequence.
+
+      Args:
+          poses: Array of joint positions (N, 17, 3)
+
+      Returns:
+          Tuple of (takeoff_frame, takeoff_velocity)
+
+      Raises:
+          ValueError: If poses array is invalid
+      """
+  ```
+
+## Code Style
+
+- **Line Length**: 100 characters (enforced by Ruff)
+- **Formatting**: Black-compatible (via Ruff)
+- **Indentation**: 4 spaces
+- **Imports**: Organized alphabetically within groups (standard library, third-party, local)
+
+## Key Patterns
+
+1. **Shared Logic**: Extract to core/ modules (pose.py, filtering.py, etc.)
+1. **Inheritance**: Use for shared behavior across jump types
+1. **Helper Functions**: Create testable, reusable functions
+1. **Function Composition**: Pass functions as parameters for flexibility
+1. **Type Aliases**: Define at module level for complex types
+
+```python
+FrameIndex = int
+PoseArray = NDArray[np.float32]  # (N, 17, 3)
+MetricsDict = TypedDict("MetricsDict", {"height": float, "contact_time": float})
+```
+
+## Video Processing Gotchas
+
+- **Read first frame** for dimensions (not OpenCV properties)
+- **Handle rotation metadata** for mobile videos
+- **Convert NumPy types** for JSON serialization (use `int()`, `float()`)
+
+## CMJ-Specific Patterns
+
+- **Use signed velocity** (not absolute magnitude)
+- **Backward search** algorithm (find peak first, then search backward)
+- **Lateral view** required for accurate analysis
+
+## Drop Jump-Specific Patterns
+
+- **Forward search** algorithm (search from ground contact)
+- **Absolute velocity** magnitude
+
+## Testing Patterns
+
+- **Test organization**: tests/ mirror src/ structure
+- **Fixtures**: Use pytest fixtures for common test data
+- **Mocking**: Mock video I/O and external dependencies
+- **Edge cases**: Test boundary conditions and error cases
+- **Coverage**: Aim for >70% overall, >85% for core algorithms
+
+## Commit Format (Conventional Commits)
+
+```
+<type>(<scope>): <description>
+
+<body (optional)>
+<footer (optional)>
+```
+
+**Types** (determines version bump):
+
+- `feat`: New feature → minor version bump (0.x.0)
+- `fix`: Bug fix → patch version bump (0.0.x)
+- `perf`: Performance improvement → patch
+- `docs`, `test`, `refactor`, `chore`, `style`, `ci`, `build` → no version bump
+
+**Examples**:
+
+- `feat: add real-time CMJ analysis streaming`
+- `fix: correct takeoff detection in backward search`
+- `test: add edge case tests for low countermovement`
+- `docs: add triple extension biomechanics guide`
+- `refactor: extract signed velocity calculation`
+
+**Important**: Never reference Claude or AI assistance in commit messages. Keep professional and technical.
+
+## Quality Gates Before Commit
+
+```bash
+uv run ruff check --fix       # Auto-fix linting issues
+uv run pyright               # Type check (strict mode)
+uv run pytest                # All 261 tests with coverage
+```
+
+Ensure:
+
+- All tests pass
+- No type errors
+- No linting errors
+- Coverage ≥74% (maintain current level)
+- Code duplication \<3%