# Implementation Plan: Screenshot Analysis Skill

**Branch**: `001-screenshot-analysis` | **Date**: 2025-11-08 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-screenshot-analysis/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.

## Summary

Create a skill that automatically finds and analyzes the most recent screenshot from a configured directory (default: ~/Pictures/Screenshots), eliminating the need for users to type file paths repeatedly. The skill uses bash scripts to locate files by modification time, applies lexicographic ordering as a tiebreaker, and passes the discovered file path to the agent's image analysis capability. Configuration is stored in a skill-specific JSON file.

## Technical Context

**Language/Version**: Bash 4.0+ (for helper scripts), Markdown (for skill definition)  
**Primary Dependencies**: Standard Unix utilities (ls, find, stat, test), jq (for JSON config parsing)  
**Storage**: JSON configuration file (optional, skill-specific: ~/.config/opencode/skills/screenshot-analysis/config.json or ~/.claude/skills/screenshot-analysis/config.json)  
**Testing**: Bash test framework (bats-core) for script unit tests, manual integration testing with Claude Code/OpenCode agents  
**Target Platform**: Linux (Ubuntu, NixOS, Fedora), Bash-compatible shells  
**Project Type**: Skill (agent capability extension) - follows skills/ directory structure from repository  
**Performance Goals**: <1 second file discovery for directories with up to 1000 files (SC-002)  
**Constraints**: Read-only filesystem access, no external network dependencies, must work with both Claude Code and OpenCode  
**Scale/Scope**: Single skill with 3-5 helper scripts, SKILL.md definition, config template, examples

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

**Note**: No project-specific constitution file exists (template only). Applying general skill development principles from repository:

✅ **Self-Contained**: Skill includes all necessary scripts, templates, and documentation  
✅ **Testable**: Each helper script can be tested independently; integration tests via agent invocation  
✅ **Technology-Agnostic**: Bash scripts are portable; skill works with both Claude Code and OpenCode  
✅ **Clear Purpose**: Eliminates repetitive path typing for screenshot analysis  
✅ **No Implementation Leakage**: SKILL.md focuses on WHAT (find screenshots) not HOW (specific bash commands)

**Status**: PASS - No violations detected

## Project Structure

### Documentation (this feature)

```text
specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```

### Source Code (repository root)

```text
skills/screenshot-analysis/
├── SKILL.md                          # Agent instructions (primary interface)
├── README.md                         # User documentation
├── scripts/
│   ├── find-latest-screenshot.sh     # Core: locate most recent screenshot
│   ├── find-nth-screenshot.sh        # Support Nth-recent (P2: "previous")
│   ├── filter-by-time.sh             # Support time filtering (P2: "from today")
│   └── load-config.sh                # Parse JSON config, return screenshot_dir
├── templates/
│   └── config.json                   # Example configuration file
└── examples/
    └── example-usage.md              # Example agent interactions

tests/
└── skills/
    └── screenshot-analysis/
        ├── unit/
        │   ├── test-find-latest.bats       # Test find-latest-screenshot.sh
        │   ├── test-find-nth.bats          # Test find-nth-screenshot.sh
        │   ├── test-filter-time.bats       # Test filter-by-time.sh
        │   └── test-load-config.bats       # Test load-config.sh
        ├── integration/
        │   └── test-skill-invocation.sh    # Manual: test with real agent
        └── fixtures/
            ├── screenshots/                # Test screenshot files
            └── configs/                    # Test config.json variants
```

**Structure Decision**: Follows repository's established skill structure (see skills/template/, skills/worklog/, skills/update-spec-kit/). Each skill is self-contained with SKILL.md, README.md, scripts/, templates/, and examples/. Tests live in a parallel tests/ directory structure.

## Complexity Tracking

**Status**: No violations - Constitution Check passed

No complexity justifications needed. The skill adheres to all principles:
- Self-contained design (scripts, templates, docs in one directory)
- Clear interface contracts (documented in contracts/)
- Test-first compatible (bats tests defined)
- Simple technology stack (bash, jq, standard tools)

---

## Phase 0: Research ✅ COMPLETE

**Output**: [research.md](./research.md)

**Key Decisions**:
- File discovery: `find -type f` with `stat` and `sort` (<1s for 1000 files)
- JSON parsing: `jq` with graceful fallback
- Timestamp tiebreaker: Lexicographic filename ordering
- Testing: bats-core framework
- Error handling: `set -euo pipefail` with descriptive messages

**Status**: All technical unknowns resolved

---

## Phase 1: Design & Contracts ✅ COMPLETE

**Outputs**:
- [data-model.md](./data-model.md) - Entities, validation rules, data flow
- [contracts/script-interface.md](./contracts/script-interface.md) - Script CLI contracts
- [quickstart.md](./quickstart.md) - 5-minute setup guide
- [AGENTS.md](../../AGENTS.md) - Updated with skill tech stack

**Key Artifacts**:
1. **Data Model**: Screenshot File, Screenshot Directory, Skill Configuration entities
2. **Script Contracts**: 4 helper scripts with defined inputs/outputs/errors
3. **Integration Flow**: SKILL.md → scripts → agent image analysis

**Post-Design Constitution Check**: ✅ PASS
- Scripts follow single-responsibility principle
- Clear separation: file discovery (bash) vs. image analysis (agent)
- No unnecessary complexity added
- Test contracts defined for all scripts

**Status**: Design complete, ready for implementation

---

## Next Phase

**Phase 2: Task Breakdown** - Use `/speckit.tasks` to generate implementation tasks

This will create `tasks.md` with prioritized implementation tasks based on user stories P1-P3.
