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

Implementation Plan: Screenshot Analysis Skill

Branch: 001-screenshot-analysis | Date: 2025-11-08 | Spec: 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)

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)

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

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 - Entities, validation rules, data flow
• contracts/script-interface.md - Script CLI contracts
• quickstart.md - 5-minute setup guide
• 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.