# 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/)
