# Tasks: Screenshot Analysis Skill **Input**: Design documents from `/specs/001-screenshot-analysis/` **Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/ **Tests**: Tests are included for this feature per quickstart.md guidance (bats-core unit tests for each script) **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. ## Format: `[ID] [P?] [Story] Description` - **[P]**: Can run in parallel (different files, no dependencies) - **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) - Include exact file paths in descriptions ## Path Conventions This is a skill project following the repository structure: - **Skill**: `skills/screenshot-analysis/` - **Tests**: `tests/skills/screenshot-analysis/` - **Fixtures**: `tests/skills/screenshot-analysis/fixtures/` --- ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Create basic skill structure following repository conventions - [ ] T001 Create skill directory structure at skills/screenshot-analysis/ with subdirs: scripts/, templates/, examples/ - [ ] T002 [P] Create test directory structure at tests/skills/screenshot-analysis/ with subdirs: unit/, integration/, fixtures/ - [ ] T003 [P] Create example config template at skills/screenshot-analysis/templates/config.json --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Core helper script that ALL user stories depend on **⚠️ CRITICAL**: This script must be complete before ANY user story implementation - [ ] T004 Implement load-config.sh in skills/screenshot-analysis/scripts/load-config.sh (config loader for all scripts) - [ ] T005 Create test fixtures: sample config.json files in tests/skills/screenshot-analysis/fixtures/configs/ - [ ] T006 Create bats test for load-config.sh in tests/skills/screenshot-analysis/unit/test-load-config.bats - [ ] T007 Verify load-config.sh passes all tests and handles edge cases (missing config, malformed JSON, missing jq) **Checkpoint**: Config loading verified - user story scripts can now use it --- ## Phase 3: User Story 1 - Quick Screenshot Analysis (Priority: P1) 🎯 MVP **Goal**: Enable users to analyze the most recent screenshot without typing file paths **Independent Test**: Take a screenshot, ask agent "look at my last screenshot", verify file found and analyzed without path input ### Tests for User Story 1 > **NOTE: Write these tests FIRST, ensure they FAIL before implementation** - [ ] T008 [P] [US1] Create test fixture: sample screenshot files in tests/skills/screenshot-analysis/fixtures/screenshots/ - [ ] T009 [US1] Create bats test for find-latest-screenshot.sh in tests/skills/screenshot-analysis/unit/test-find-latest.bats - [ ] T010 [US1] Add test case: finds latest screenshot by modification time - [ ] T011 [US1] Add test case: excludes symlinks (finds regular files only) - [ ] T012 [US1] Add test case: handles empty directory gracefully - [ ] T013 [US1] Add test case: applies lexicographic tiebreaker for same timestamp - [ ] T014 [US1] Add test case: directory not found error handling - [ ] T015 [US1] Add test case: permission denied error handling ### Implementation for User Story 1 - [ ] T016 [US1] Implement find-latest-screenshot.sh in skills/screenshot-analysis/scripts/find-latest-screenshot.sh - [ ] T017 [US1] Add shebang, set -euo pipefail, and help flag support - [ ] T018 [US1] Implement directory validation (exists, readable) - [ ] T019 [US1] Implement find command with -type f filter (excludes symlinks per FR-002a) - [ ] T020 [US1] Implement format filtering (.png, .jpg, .jpeg case-insensitive per FR-003) - [ ] T021 [US1] Implement stat for modification time extraction - [ ] T022 [US1] Implement sort with timestamp + lexicographic tiebreaker (per FR-002) - [ ] T023 [US1] Implement error messages for directory not found, permission denied - [ ] T024 [US1] Make script executable (chmod +x) - [ ] T025 [US1] Run bats tests and verify all pass - [ ] T026 [US1] Create SKILL.md in skills/screenshot-analysis/SKILL.md with US1 functionality only - [ ] T027 [US1] Add frontmatter metadata (name: screenshot-analysis, description per FR-005) - [ ] T028 [US1] Add "When to Use" section with natural language triggers from FR-005 - [ ] T029 [US1] Add "Process" section showing load-config.sh and find-latest-screenshot.sh invocation - [ ] T030 [US1] Add error handling instructions for empty directory case - [ ] T031 [US1] Add requirements section (bash, find, stat, sort, jq) - [ ] T032 [P] [US1] Create README.md in skills/screenshot-analysis/README.md for users - [ ] T033 [P] [US1] Create example-usage.md in skills/screenshot-analysis/examples/example-usage.md **Checkpoint**: US1 complete - user can analyze latest screenshot without typing paths --- ## Phase 4: User Story 2 - Reference Previous Screenshots (Priority: P2) **Goal**: Enable users to reference Nth-recent screenshots and filter by time **Independent Test**: Take 3 screenshots, ask "show me the previous screenshot", verify 2nd-most-recent is found ### Tests for User Story 2 - [ ] T034 [P] [US2] Create bats test for find-nth-screenshot.sh in tests/skills/screenshot-analysis/unit/test-find-nth.bats - [ ] T035 [US2] Add test case: finds Nth most recent screenshot (N=2, N=3) - [ ] T036 [US2] Add test case: handles N exceeding available count - [ ] T037 [US2] Add test case: validates N is positive integer - [ ] T038 [P] [US2] Create bats test for filter-by-time.sh in tests/skills/screenshot-analysis/unit/test-filter-time.bats - [ ] T039 [US2] Add test case: filters screenshots from today - [ ] T040 [US2] Add test case: filters screenshots from last N minutes - [ ] T041 [US2] Add test case: validates time specification format ### Implementation for User Story 2 - [ ] T042 [P] [US2] Implement find-nth-screenshot.sh in skills/screenshot-analysis/scripts/find-nth-screenshot.sh - [ ] T043 [US2] Add N parameter validation (positive integer check) - [ ] T044 [US2] Reuse find-latest-screenshot.sh logic with sed -n for Nth selection - [ ] T045 [US2] Implement error for N exceeding count - [ ] T046 [US2] Make script executable - [ ] T047 [US2] Run bats tests and verify all pass - [ ] T048 [P] [US2] Implement filter-by-time.sh in skills/screenshot-analysis/scripts/filter-by-time.sh - [ ] T049 [US2] Implement TIME_SPEC parsing (today, Nm, Nh, Nd) - [ ] T050 [US2] Implement find -newermt for "today" filter - [ ] T051 [US2] Implement find -mmin for minute-based filtering - [ ] T052 [US2] Implement validation for invalid time specs - [ ] T053 [US2] Make script executable - [ ] T054 [US2] Run bats tests and verify all pass - [ ] T055 [US2] Update SKILL.md to add US2 natural language triggers ("previous screenshot", "from today") - [ ] T056 [US2] Add find-nth-screenshot.sh invocation examples to SKILL.md - [ ] T057 [US2] Add filter-by-time.sh invocation examples to SKILL.md - [ ] T058 [P] [US2] Update README.md with US2 usage examples - [ ] T059 [P] [US2] Update example-usage.md with Nth screenshot and time filtering examples **Checkpoint**: US1 + US2 complete - users can reference any recent screenshot or filter by time --- ## Phase 5: User Story 3 - Custom Screenshot Directory Support (Priority: P3) **Goal**: Allow users to configure custom screenshot directories **Independent Test**: Create config.json with custom directory, take screenshot there, verify skill finds it ### Tests for User Story 3 - [ ] T060 [US3] Extend test-load-config.bats with custom directory path tests - [ ] T061 [US3] Add test case: loads custom directory from config.json - [ ] T062 [US3] Add test case: expands tilde in config path - [ ] T063 [US3] Add test case: validates custom directory exists - [ ] T064 [US3] Extend test-find-latest.bats to test with custom config directory ### Implementation for User Story 3 - [ ] T065 [US3] Verify load-config.sh already handles custom directories (implemented in T004) - [ ] T066 [US3] Update SKILL.md to document custom config file usage - [ ] T067 [US3] Add configuration section to SKILL.md with config.json location and format - [ ] T068 [US3] Add error handling instructions for invalid custom directory - [ ] T069 [P] [US3] Update README.md with configuration instructions - [ ] T070 [P] [US3] Update templates/config.json with comments and examples - [ ] T071 [US3] Run all bats tests with custom config scenarios - [ ] T072 [P] [US3] Add configuration examples to example-usage.md **Checkpoint**: US1 + US2 + US3 complete - all user stories functional independently --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Final validation and documentation across all user stories - [ ] T073 [P] Create integration test script in tests/skills/screenshot-analysis/integration/test-skill-invocation.sh - [ ] T074 Add manual test checklist: deploy to agent, test natural language triggers, verify image analysis - [ ] T075 [P] Add installation section to README.md (for Claude Code and OpenCode) - [ ] T076 [P] Add troubleshooting section to README.md (jq not found, empty directory, permissions) - [ ] T077 Verify all scripts have correct shebang and execute permissions - [ ] T078 [P] Verify all bats tests pass in clean environment - [ ] T079 Run performance validation: 1000 files in <1 second (SC-002) - [ ] T080 [P] Add skill to main repository README.md in skills section - [ ] T081 Validate against quickstart.md success criteria checklist - [ ] T082 Final review: SKILL.md follows template structure from skills/template/ --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies - can start immediately - **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories - **User Stories (Phase 3-5)**: All depend on Foundational phase completion - User stories can then proceed in parallel (if staffed) - Or sequentially in priority order (P1 → P2 → P3) - **Polish (Phase 6)**: Depends on all desired user stories being complete ### User Story Dependencies - **User Story 1 (P1)**: Depends only on Foundational (Phase 2) - No dependencies on other stories - **User Story 2 (P2)**: Depends only on Foundational (Phase 2) - Independent of US1 (own scripts) - **User Story 3 (P3)**: Depends only on Foundational (Phase 2) - Independent of US1/US2 (config already in load-config.sh) ### Within Each User Story - Tests MUST be written and FAIL before implementation - Scripts before SKILL.md updates - SKILL.md before README.md/examples - Bats tests pass before moving to next story ### Parallel Opportunities **Phase 1 (Setup)**: - T002 and T003 can run in parallel with T001 **Phase 2 (Foundational)**: - T005 and T006 can run in parallel (after T004) **Phase 3 (US1)**: - T008 can run in parallel (test fixtures) - T032 and T033 can run in parallel (after SKILL.md complete) **Phase 4 (US2)**: - T034 and T038 can run in parallel (different test files) - T042 and T048 can run in parallel (different script files) - T058 and T059 can run in parallel (after SKILL.md updates) **Phase 5 (US3)**: - T069, T070, T072 can run in parallel (different documentation files) **Phase 6 (Polish)**: - T073, T075, T076, T078, T080 can all run in parallel **Across User Stories** (if team capacity allows): - Once Phase 2 completes, US1, US2, US3 can all start in parallel by different developers --- ## Parallel Example: User Story 1 ```bash # Launch tests together (after fixtures created): Task: "Add test case: finds latest screenshot by modification time" Task: "Add test case: excludes symlinks" Task: "Add test case: handles empty directory gracefully" # Launch documentation together (after SKILL.md complete): Task: "Create README.md for users" Task: "Create example-usage.md" ``` --- ## Parallel Example: Multiple User Stories ```bash # After Foundational (Phase 2) completes, launch in parallel: Developer A: Focus on User Story 1 (T008-T033) Developer B: Focus on User Story 2 (T034-T059) Developer C: Focus on User Story 3 (T060-T072) # Each developer can work independently on their story's scripts ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup (T001-T003) 2. Complete Phase 2: Foundational (T004-T007) - CRITICAL 3. Complete Phase 3: User Story 1 (T008-T033) 4. **STOP and VALIDATE**: Test US1 independently with real agent 5. Deploy/demo basic screenshot analysis capability **Result**: Core value delivered - users can analyze latest screenshot without typing paths ### Incremental Delivery 1. Complete Setup + Foundational → Config loading works 2. Add User Story 1 → Test independently → **Deploy MVP** ✅ 3. Add User Story 2 → Test independently → Deploy enhanced version (Nth, time filtering) 4. Add User Story 3 → Test independently → Deploy full feature (custom directories) 5. Polish → Final validation → Production ready Each story adds value without breaking previous stories. ### Parallel Team Strategy With multiple developers: 1. Team completes Setup + Foundational together (T001-T007) 2. Once Foundational is done: - Developer A: User Story 1 (T008-T033) - Core functionality - Developer B: User Story 2 (T034-T059) - Enhanced referencing - Developer C: User Story 3 (T060-T072) - Custom config 3. Stories complete independently, integrate via shared load-config.sh 4. Team converges on Polish (T073-T082) --- ## Task Summary **Total Tasks**: 82 **By Phase**: - Phase 1 (Setup): 3 tasks - Phase 2 (Foundational): 4 tasks (BLOCKING) - Phase 3 (US1 - P1): 26 tasks (MVP) - Phase 4 (US2 - P2): 26 tasks - Phase 5 (US3 - P3): 13 tasks - Phase 6 (Polish): 10 tasks **By User Story**: - US1 (P1): 26 tasks - Core screenshot analysis - US2 (P2): 26 tasks - Nth screenshot + time filtering - US3 (P3): 13 tasks - Custom directory configuration **Parallel Opportunities**: 21 tasks marked [P] (25% can run in parallel) **MVP Scope** (Recommended): Phase 1 + 2 + 3 (33 tasks) delivers core value --- ## Notes - [P] tasks = different files, no dependencies on incomplete tasks - [Story] label maps task to specific user story (US1, US2, US3) - Each user story is independently testable - Tests use bats-core framework per research.md decisions - Scripts follow contract specifications from contracts/script-interface.md - All scripts use `set -euo pipefail` error handling per research.md - Performance target: <1s for 1000 files (validated in T079) - Skill structure follows repository conventions (skills/template/)