skills/specs/001-screenshot-analysis/tasks.md

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

# 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

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