#+TITLE: Issue Triage and Playwright-Visit Skill Implementation
#+DATE: 2025-12-29
#+KEYWORDS: issue-triage, playwright, browser-automation, design-decisions, skill-deployment, web-search
#+COMMITS: 12
#+COMPRESSION_STATUS: uncompressed

* Session Summary
** Date: 2025-12-29 (Late night session, continuation from 2025-12-28)
** Focus Area: Clearing design decision backlog, implementing playwright-visit skill

* Accomplishments
- [X] Closed skills-vb5: Resolved web search design questions
- [X] Closed skills-al5: Decided to keep repo-setup-verification as prompt doc (not skill)
- [X] Closed skills-u3d: Confirmed agent judgment from description is sufficient for triggers
- [X] Closed skills-1n3: Gemini CLI skills - wait for native support, no MCP
- [X] Closed skills-2xo: Added README.md for web-search skill
- [X] Closed skills-qeh: Added README.md for web-research skill
- [X] Closed skills-gq9: Deferred structured skill reference schema
- [X] Closed skills-hin: Parked ADR-001 skills-molecules integration
- [X] Closed skills-rpf: Implemented playwright-visit skill for browser automation
- [X] Moved skills-e8h to dotfiles repo (waybar+niri belongs there)
- [X] Fixed playwright-visit networkidle timeout issue
- [X] Tested playwright-visit on NYT homepage successfully
- [X] Added playwright-visit to dotfiles deployment (commit ready, deploy blocked by network)

* Key Decisions
** Decision 1: Web search skills - keep two separate
- Context: Had brainstorm doc with open questions about single vs multiple skills
- Options considered:
  1. Single smart skill that figures out what to do
  2. Two skills: web-search (quick) and web-research (deep)
- Rationale: Claude Code has built-in WebSearch now, so web-search is mainly for OpenCode. Keep separate for clear intent.
- Impact: web-search deployed to OpenCode only, web-research to both

** Decision 2: Repo-setup-verification - keep as prompt doc
- Context: Dotfiles has repo-setup-prompt.md for verifying agent setup
- Options considered:
  1. Convert to skill
  2. Keep as prompt doc
- Rationale: Claude can read it when asked "verify my repo setup". Skill wrapper adds no value for instructions-only content.
- Impact: No new skill created, doc stays in dotfiles

** Decision 3: Skill trigger conditions - agent judgment sufficient
- Context: How should agents know when to invoke skills?
- Options considered: Frontmatter triggers, file detection, agent judgment, beads hooks, LLM pattern matching
- Rationale: Current approach (description + "When to Use" section) works well. Infrastructure for triggers is premature.
- Impact: No new trigger mechanism, focus on good skill documentation

** Decision 4: Gemini CLI skills - wait for native support
- Context: Skills don't work with Gemini CLI
- Options considered:
  1. MCP extension (gemini-cli-skillz)
  2. Wait for native support (issue #11506)
  3. Manual GEMINI.md references
- Rationale: User doesn't want MCP. Native support pending. GEMINI.md workaround sufficient.
- Impact: No Gemini skill integration for now

** Decision 5: Skills-molecules integration - park the ADR
- Context: ADR-001 describes complex integration between skills and beads molecules
- Rationale: Current simpler approach works well. Skills as standalone entrypoints. Molecules not actively used.
- Impact: ADR status changed to "Parked", revisit when orchestration needs grow

** Decision 6: Structured skill reference schema - defer
- Context: Proposed schema for molecule→skill invocation with typed inputs/outputs
- Rationale: Premature infrastructure. Skills work well with agent reading SKILL.md directly.
- Impact: No schema implementation, revisit if programmatic workflows become active

* Problems & Solutions
| Problem | Solution | Learning |
|---------|----------|----------|
| playwright networkidle timeout on NYT | Changed to domcontentloaded + wait param | Heavy sites need different wait strategy |
| Dotfiles deploy failed - delbaker flake issue | Unrelated to skill, network issues compounded | Flake input mismatches need manual update |
| GitHub API 504 timeout | Defer deploy, changes committed | Network instability throughout session |
| Gemini CLI lacks skill support | Use GEMINI.md to reference skill paths | Native support pending, MCP rejected |

* Technical Details

** Code Changes
- Total files modified: ~15
- Key files changed:
  - =skills/playwright-visit/= - New skill (SKILL.md, README.md, flake.nix, scripts/visit.py)
  - =skills/web-search/README.md= - New human documentation
  - =skills/web-research/README.md= - New human documentation
  - =web_search_brainstorm.md= - Added resolution section
  - =docs/adr/001-skills-molecules-integration.md= - Updated status to Parked
  - =~/proj/dotfiles/home/claude.nix= - Added playwright-visit to skills lists

** New Files Created
- =skills/playwright-visit/SKILL.md= - Agent instructions for browser automation
- =skills/playwright-visit/README.md= - Human documentation
- =skills/playwright-visit/flake.nix= - Nix devShell with playwright
- =skills/playwright-visit/scripts/visit.py= - CLI with screenshot/text/html/pdf commands
- =skills/web-search/README.md= - Human docs
- =skills/web-research/README.md= - Human docs

** Commands Used
#+begin_src bash
# Test playwright-visit
cd skills/playwright-visit && nix develop --command ./scripts/visit.py --help
./scripts/visit.py screenshot "https://example.com" /tmp/test.png
./scripts/visit.py text "https://example.com"
./scripts/visit.py screenshot "https://www.nytimes.com" /tmp/nyt.png --wait 3000

# Deploy dotfiles (failed due to network)
cd ~/proj/dotfiles && ./bin/deploy.sh
nix flake update skills delbaker
#+end_src

** Architecture Notes
- playwright-visit uses NixOS system chromium (no browser download)
- domcontentloaded wait strategy more reliable than networkidle for heavy sites
- Skills deployed via Nix home-manager symlinks to ~/.claude/skills/

* Process and Workflow

** What Worked Well
- Rapid issue triage - many design decisions resolved quickly
- Pattern: show issue → analyze → decide → close with rationale
- Testing playwright-visit immediately after implementation caught timeout bug
- Using playwright to screenshot NYT demonstrated real-world utility

** What Was Challenging
- Network instability (GitHub API timeouts, cachix DNS issues, git remote down)
- Flake input mismatches requiring manual updates
- Dotfiles deploy blocked by multiple issues (delbaker flake, network)

* Learning and Insights

** Technical Insights
- Playwright networkidle waits for all network activity to stop - too strict for modern sites
- domcontentloaded + explicit wait is more reliable pattern
- NixOS playwright uses system chromium via executable_path, avoiding binary downloads

** Process Insights
- Many open design issues were actually resolved by "current approach is sufficient"
- Parking/deferring premature infrastructure is better than building unused complexity
- Skills work well as standalone - molecule integration adds overhead without proportional benefit

** Architectural Insights
- Claude Code built-in WebSearch/WebFetch reduces need for web-search skill
- Agent judgment from description is the right trigger mechanism - no infrastructure needed
- GEMINI.md manual skill references work until native support lands

* Context for Future Work

** Open Questions
- When will Gemini CLI get native skill support?
- Should playwright-visit support authentication (storage_state)?
- Add --viewport option for different screen sizes?

** Next Steps
- Deploy dotfiles when network stabilizes
- Test playwright-visit from deployed ~/.claude/skills/ location
- Consider adding playwright-visit to more repos via .skills manifest
- Remaining ready issues: x2l (orch hooks), pdg (AT-SPI), ebl (vision benchmark), 6e3 (search history), 8d9 (orch patterns)

** Related Work
- [[file:2025-12-28-niri-robustness-opencode-research-readme-update.org][Earlier 2025-12-28 session]] - niri fixes, OpenCode research
- [[file:2025-12-28-code-review-skill-creation-worklog-cleanup.org][2025-12-28 morning session]] - code-review skill creation

* Raw Notes
- Session ran late night into early morning (Dec 28 → Dec 29)
- Cleared significant design decision backlog
- Many issues closed as "current approach sufficient" or "deferred/parked"
- playwright-visit is first skill with its own flake.nix devShell
- NYT headline captured: "Trump and Zelensky Meet to Iron Out Peace Plan, but Deal Remains Elusive"

** Issues Closed This Session
| Issue | Title | Resolution |
|-------|-------|------------|
| skills-vb5 | Resolve web search design questions | Keep 2 skills, web-search for OpenCode only |
| skills-al5 | Consider repo-setup-verification skill | Keep as prompt doc in dotfiles |
| skills-u3d | Define skill trigger conditions | Agent judgment sufficient |
| skills-1n3 | Set up agent skills for Gemini CLI | Wait for native support, no MCP |
| skills-2xo | Add README.md for web-search | Created |
| skills-qeh | Add README.md for web-research | Created |
| skills-gq9 | Define structured skill reference schema | Deferred |
| skills-hin | ADR: Skills and Molecules Integration | Parked |
| skills-rpf | Implement playwright-visit skill | Implemented and tested |

* Session Metrics
- Commits made: 12 (skills repo) + 2 (dotfiles)
- Files touched: ~15
- Lines added/removed: +500/-20 (estimated)
- Issues closed: 9
- New skills created: 1 (playwright-visit)
- READMEs added: 3 (web-search, web-research, playwright-visit)
- Tests added: 0 (manual testing only)