From 82445dd8390cf720d73f179b966f5c519fb696ea Mon Sep 17 00:00:00 2001 From: dan Date: Sat, 27 Dec 2025 10:06:02 -0500 Subject: [PATCH] refactor(worklog): consolidate skill prompt - Remove inline section list, reference template directly - Merge Guidelines and Remember into single Principles section - Extract skill directory path, use relative references 127 -> 98 lines (-23%) --- .beads/issues.jsonl | 6 ++-- skills/worklog/SKILL.md | 64 ++++++++++++----------------------------- 2 files changed, 21 insertions(+), 49 deletions(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 988dded..2f4adf4 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -86,7 +86,7 @@ {"id":"skills-p2o","title":"Refactor update-agent-context.sh: array+loop for agents","description":"File: .specify/scripts/bash/update-agent-context.sh (772 lines)\n\nIssues:\n- 12 nearly-identical if-blocks in update_all_existing_agents() (lines 632-701)\n- Should be refactored into loop with array of agent configurations\n- Current pattern repeats: if [[ -f \"$CLAUDE_FILE\" ]]; then update_agent_file...\n\nFix:\n- Create AGENTS array with (file, name, format) tuples\n- Replace 12 if-blocks with single for loop\n- Estimated reduction: 60 lines\n\nSeverity: HIGH","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T02:50:57.385820971-05:00","updated_at":"2025-12-25T01:44:58.370191619-05:00","closed_at":"2025-12-25T01:44:58.370191619-05:00","close_reason":"update-agent-context.sh is .specify upstream code, not maintained here"} {"id":"skills-p3v","title":"Cross-language FFI wormholes via LSP","description":"Bridge FFI boundaries where standard LSPs go blind:\n- Rust extern C → clangd lookup\n- Go CGO → match C symbols\n- Python FFI → trace bindings\n\nGenerate synthetic go-to-definition maps. When hovering over C call in Rust, intercept hover request, query C LSP, inject C definition into Rust tooltip.\n\nEnables seamless polyglot navigation.","status":"open","priority":4,"issue_type":"feature","created_at":"2025-12-24T02:29:57.597602745-05:00","updated_at":"2025-12-24T02:29:57.597602745-05:00"} {"id":"skills-pdg","title":"Enable AT-SPI for UI tree access","description":"## Findings\n\nAT-SPI (Assistive Technology Service Provider Interface) provides semantic UI tree access - buttons, labels, text fields, their states and coordinates.\n\n### Current state\n- AT-SPI is **disabled** on this NixOS system\n- Environment has `NO_AT_BRIDGE=1` and `GTK_A11Y=none`\n- No apps are exposing accessibility info\n\n### To enable\n```nix\nservices.gnome.at-spi2-core.enable = true;\n```\n\nThen rebuild and re-login (apps must start fresh to register with bus).\n\n### App support\n- **GTK apps**: Should work automatically\n- **Qt apps**: Need `QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1` env var\n- **Electron**: Varies by app, often poor support\n\n### Trade-offs\n- Adds runtime overhead to all GTK/Qt apps\n- May want as boot-time option rather than always-on\n- Only useful for automation/accessibility use cases\n\n### Tools once enabled\n- `python3-pyatspi` / `dogtail` for querying UI tree\n- `accerciser` for visual inspection of accessibility tree\n\n### Next steps\n1. Add NixOS option (possibly as boot-time toggle)\n2. Test with common apps (Firefox, terminals, etc.)\n3. Build skill to query UI elements\n\n## Related\nParent epic: skills-kg7 (Desktop automation for Wayland/niri)","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T13:59:55.799402507-08:00","updated_at":"2025-12-17T13:59:55.799402507-08:00"} -{"id":"skills-prt","title":"worklog: remove inline section list, reference template","description":"SKILL.md lists 11 sections that duplicate worklog-template.org. Will drift. Replace with directive to parse sections from template dynamically. Found by bloat lens review.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:16.811093872-05:00","updated_at":"2025-12-25T02:03:16.811093872-05:00"} +{"id":"skills-prt","title":"worklog: remove inline section list, reference template","description":"SKILL.md lists 11 sections that duplicate worklog-template.org. Will drift. Replace with directive to parse sections from template dynamically. Found by bloat lens review.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:16.811093872-05:00","updated_at":"2025-12-27T10:05:51.513685966-05:00","closed_at":"2025-12-27T10:05:51.513685966-05:00","close_reason":"Closed"} {"id":"skills-pu4","title":"Clean up stale beads.left.jsonl merge artifact","description":"bd doctor flagged multiple JSONL files. beads.left.jsonl is empty merge artifact that should be removed: git rm .beads/beads.left.jsonl","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.292221449-08:00","updated_at":"2025-11-30T12:37:49.916795223-08:00","closed_at":"2025-11-30T12:37:49.916795223-08:00"} {"id":"skills-qeh","title":"Add README.md for web-research skill","description":"web-research skill has SKILL.md and scripts but no README.md. AGENTS.md says README.md is for humans, contains installation instructions, usage examples, prerequisites.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:14.475647113-08:00","updated_at":"2025-11-30T12:00:30.309340468-08:00","dependencies":[{"issue_id":"skills-qeh","depends_on_id":"skills-vb5","type":"blocks","created_at":"2025-11-30T12:01:30.278784381-08:00","created_by":"daemon","metadata":"{}"}]} {"id":"skills-r5c","title":"Extract shared logging library from scripts","description":"Duplicated logging/color functions across multiple scripts:\n- bin/deploy-skill.sh\n- skills/tufte-press/scripts/generate-and-build.sh\n- Other .specify scripts\n\nPattern repeated:\n- info(), warn(), error() functions\n- Color definitions (RED, GREEN, etc.)\n- Same 15-20 lines in each file\n\nFix:\n- Create scripts/common-logging.sh\n- Source from all scripts that need it\n- Estimated reduction: 30+ lines of duplication\n\nSeverity: MEDIUM","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-24T02:50:58.324852578-05:00","updated_at":"2025-12-24T02:50:58.324852578-05:00"} @@ -95,7 +95,7 @@ {"id":"skills-s92","title":"Add tests for config injection (deploy-skill.sh)","description":"File: bin/deploy-skill.sh (lines 112-137)\n\nCritical logic with NO test coverage:\n- Idempotency (running twice should be safe)\n- Correct brace matching in Nix\n- Syntax validity of injected config\n- Rollback on failure\n\nRisk: MEDIUM-HIGH - can break dotfiles Nix config\n\nFix:\n- Test idempotent injection\n- Validate Nix syntax after injection\n- Test with malformed input\n\nSeverity: MEDIUM","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-24T02:51:01.314513824-05:00","updated_at":"2025-12-24T02:51:01.314513824-05:00"} {"id":"skills-ty7","title":"Define trace levels (audit vs debug)","description":"Two trace levels to manage noise vs utility:\n\n1. Audit trace (minimal, safe, always on):\n - skill id/ref, start/end\n - high-level checkpoints\n - artifact hashes/paths\n - exit status\n\n2. Debug trace (opt-in, verbose):\n - tool calls with args\n - stdout/stderr snippets\n - expanded inputs\n - timing details\n\nConsider OpenTelemetry span model as reference.\nGPT proposed this; Gemini focused on rotation/caps instead.","status":"in_progress","priority":3,"issue_type":"task","created_at":"2025-12-23T19:49:48.514684945-05:00","updated_at":"2025-12-23T20:05:23.244193346-05:00"} {"id":"skills-u3d","title":"Define skill trigger conditions","description":"How does an agent know WHEN to apply a skill/checklist?\n\nOptions:\n- frontmatter triggers: field with patterns\n- File-based detection\n- Agent judgment from description\n- Beads hooks on state transitions\n- LLM-based pattern detection","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-23T17:59:09.69468767-05:00","updated_at":"2025-12-23T17:59:09.69468767-05:00"} -{"id":"skills-uan","title":"worklog: merge Guidelines and Remember sections","description":"Guidelines (8 points) and Remember (6 points) sections overlap significantly - both emphasize comprehensiveness, future context, semantic compression. Consolidate into single principles list. Found by bloat lens review.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:16.148596791-05:00","updated_at":"2025-12-25T02:03:16.148596791-05:00"} +{"id":"skills-uan","title":"worklog: merge Guidelines and Remember sections","description":"Guidelines (8 points) and Remember (6 points) sections overlap significantly - both emphasize comprehensiveness, future context, semantic compression. Consolidate into single principles list. Found by bloat lens review.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:16.148596791-05:00","updated_at":"2025-12-27T10:05:51.527595332-05:00","closed_at":"2025-12-27T10:05:51.527595332-05:00","close_reason":"Closed"} {"id":"skills-uz4","title":"Compare RESUMABILITY.md with upstream","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.897754095-08:00","updated_at":"2025-12-03T20:19:29.384645842-08:00","closed_at":"2025-12-03T20:19:29.384645842-08:00","dependencies":[{"issue_id":"skills-uz4","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.899671178-08:00","created_by":"daemon","metadata":"{}"}]} {"id":"skills-vb5","title":"Resolve web search design questions","description":"web_search_brainstorm.md has unanswered design questions: single smart skill vs explicit flags, specific sources priority, raw links vs summaries. Need user input to finalize web-search/web-research direction.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.482270742-08:00","updated_at":"2025-11-30T11:58:33.482270742-08:00"} {"id":"skills-vjm","title":"Refactor update-agent-context.sh: reduce nesting depth","description":"File: .specify/scripts/bash/update-agent-context.sh\n\nIssues:\n- update_existing_agent_file() has 4-level deep nesting (lines 360-499)\n- State machine with multiple variables: in_tech_section, in_changes_section, tech_entries_added\n- 70+ lines of while loop processing\n\nFix:\n- Extract file processing to separate function\n- Consider sed/awk for line-based transformations\n- Use guard clauses to reduce nesting\n\nSeverity: HIGH","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T02:50:57.874439288-05:00","updated_at":"2025-12-25T01:44:58.38265672-05:00","closed_at":"2025-12-25T01:44:58.38265672-05:00","close_reason":"update-agent-context.sh is .specify upstream code, not maintained here"} @@ -103,4 +103,4 @@ {"id":"skills-wm9","title":"Research Steve Yegge's orchestration work","description":"Steve Yegge is working on something new related to AI orchestration. Research what it is and how it might inform our skills+molecules integration design.\n\nBlocks: skills-hin (ADR finalization)","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T02:41:47.848905848-05:00","updated_at":"2025-12-24T02:42:24.40239935-05:00","closed_at":"2025-12-24T02:42:24.40239935-05:00","close_reason":"Not needed - just parking the ADR work"} {"id":"skills-x2l","title":"Investigate hooks for parallel orch queries","description":"When using orch skill, it would be useful to spin off multiple model queries in parallel automatically (e.g., gemini + gpt simultaneously). Explore if Claude Code hooks can trigger parallel background processes when the orch skill is invoked.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-06T19:29:00.165752425-08:00","updated_at":"2025-12-06T19:29:00.165752425-08:00"} {"id":"skills-x33","title":"Add tests for branch name generation","description":"File: .specify/scripts/bash/create-new-feature.sh (lines 137-181)\n\nCritical logic with NO test coverage:\n- Word filtering with stop-words\n- Acronym detection\n- Unicode/special character handling\n- Max length boundary (244 bytes)\n- Empty/single-word descriptions\n\nRisk: HIGH - affects all branch creation\n\nFix:\n- Create test suite with edge cases\n- Test stop-word filtering accuracy\n- Test boundary conditions\n\nSeverity: HIGH","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-24T02:51:00.311664646-05:00","updated_at":"2025-12-24T02:51:00.311664646-05:00"} -{"id":"skills-yxv","title":"worklog: extract hardcoded path to variable","description":"SKILL.md repeats ~/.claude/skills/worklog/ path 4-5 times. Define SKILL_ROOT once, reference throughout. Found by bloat+smells lens review.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:15.831699081-05:00","updated_at":"2025-12-25T02:03:15.831699081-05:00"} +{"id":"skills-yxv","title":"worklog: extract hardcoded path to variable","description":"SKILL.md repeats ~/.claude/skills/worklog/ path 4-5 times. Define SKILL_ROOT once, reference throughout. Found by bloat+smells lens review.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:15.831699081-05:00","updated_at":"2025-12-27T10:05:51.532722628-05:00","closed_at":"2025-12-27T10:05:51.532722628-05:00","close_reason":"Closed"} diff --git a/skills/worklog/SKILL.md b/skills/worklog/SKILL.md index aa8d265..c939e19 100644 --- a/skills/worklog/SKILL.md +++ b/skills/worklog/SKILL.md @@ -7,6 +7,8 @@ description: Create comprehensive structured org-mode worklogs documenting work Create comprehensive structured worklogs that document work sessions with rich context for future reference. +**Skill directory:** `~/.claude/skills/worklog/` (contains scripts/, templates/) + ## When to Use Invoke this skill when the user requests: @@ -38,89 +40,59 @@ Create the `docs/worklogs/` directory if it doesn't exist. Use the helper script to suggest the filename: ```bash -~/.claude/skills/worklog/scripts/suggest-filename.sh +scripts/suggest-filename.sh ``` ## Structure -Read the complete template from: `~/.claude/skills/worklog/templates/worklog-template.org` +Read and follow the template: `templates/worklog-template.org` -The worklog must follow this template structure exactly. - -Key sections to include: -1. **Metadata** - Title, date, keywords, commits, compression status -2. **Session Summary** - Date, focus area -3. **Accomplishments** - Checkbox list of what was done -4. **Key Decisions** - Context, options, rationale, impact -5. **Problems & Solutions** - Table format with learnings -6. **Technical Details** - Code changes, commands, architecture notes -7. **Process & Workflow** - What worked, what was challenging -8. **Learning & Insights** - Technical, process, and architectural insights -9. **Context for Future Work** - Open questions, next steps, related work -10. **Raw Notes** - Additional context -11. **Session Metrics** - Quantitative summary +The template defines all required sections. Parse it directly rather than relying on this summary. ## Helper Scripts **Extract Git Metrics:** ```bash -~/.claude/skills/worklog/scripts/extract-metrics.sh +scripts/extract-metrics.sh ``` Outputs: commits made, files touched, lines added/removed **Suggest Filename:** ```bash -~/.claude/skills/worklog/scripts/suggest-filename.sh +scripts/suggest-filename.sh ``` Analyzes recent commits to suggest a descriptive filename **Find Related Logs:** ```bash -~/.claude/skills/worklog/scripts/find-related-logs.sh "keyword1 keyword2" +scripts/find-related-logs.sh "keyword1 keyword2" ``` Searches previous worklogs for context continuity -## Guidelines +## Principles -1. **Be Comprehensive** - Include more information rather than less. This worklog will be compressed later. - -2. **Focus on Facts and Context** - Document what happened, why decisions were made, and how problems were solved. - -3. **Include Code and Commands** - Show actual code snippets, error messages, and commands used. - -4. **Capture the Journey** - Document false starts, debugging sessions, and the path to the solution. - -5. **Think About Future You** - What would you want to know if you encountered this situation in 6 months? - -6. **No Premature Optimization** - Don't worry about redundancy or verbosity. Semantic compression will handle distillation later. - -7. **Minimum Length** - Aim for at least 3-5KB of content. Thorough worklogs typically run 5-15KB or more. - -8. **Pull Previous Context** - Use the find-related-logs script to reference related work and maintain continuity. +1. **Be thorough** - More information is better; these logs can be distilled later +2. **Document the journey** - Include false starts, debugging, and the path to the solution +3. **Focus on why** - Decisions, rationale, and context matter more than what +4. **Include specifics** - Code snippets, commands, error messages help reconstruct solutions +5. **Think ahead** - What would you need to know in 6 months? +6. **Pull previous context** - Use find-related-logs for continuity across sessions +7. **Aim for 3-5KB minimum** - Thorough logs typically run 5-15KB ## Process 1. Gather git context using the Bash tool with commands shown above 2. Run helper scripts to extract metrics and suggest filename -3. Read the complete template from `~/.claude/skills/worklog/templates/worklog-template.org` +3. Read the complete template from `templates/worklog-template.org` 4. Search for related previous worklogs using the find-related-logs script 5. Fill in all template sections with detailed information from the session 6. Ensure the `docs/worklogs/` directory exists (create if needed) 7. Save the worklog with the suggested filename 8. Verify metadata frontmatter is complete -## Remember - -- This is raw material for future semantic compression - be thorough -- Semantic compression is a planned workflow that will distill and index these logs -- Decisions and rationale are crucial - explain the "why" -- Technical details help reconstruct solutions -- Process insights prevent future mistakes -- The journey is as important as the destination - ## Requirements - Must be in a git repository - Saves to `docs/worklogs/` directory (will create if needed) - Outputs org-mode format -- Requires helper scripts in `~/.claude/skills/worklog/scripts/` +- Requires helper scripts in `scripts/`