From b0e7860c37eef304421209b2be688e2d24972c47 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 1 Sep 2026 11:47:44 +0100 Subject: [PATCH] claude: streamline skills catalog and enable autonomous execution Prune redundant, superseded, and low-utility skills to reduce context load and eliminate routing ambiguity. Move standalone CLI utilities to docs/recipes/ and scripts/. Enable model invocation for core problem-solving skills while retaining explicit user-invoked flags on procedural workflows. --- claude/SKILLS.md | 99 +++++++------------ claude/skills/adversarial-reviewer/SKILL.md | 41 -------- claude/skills/ast-grep/SKILL.md | 65 ------------ claude/skills/code-quality-reviewer/SKILL.md | 35 ------- claude/skills/code-reuse-reviewer/SKILL.md | 33 ------- claude/skills/code-review/SKILL.md | 1 - claude/skills/code-walkthrough/SKILL.md | 62 ------------ claude/skills/convert-audio-mono/SKILL.md | 31 ------ claude/skills/design-discussion/SKILL.md | 1 - claude/skills/diagnose-and-propose/SKILL.md | 1 - .../skills/doc-clarity-opportunity/SKILL.md | 23 ----- claude/skills/educational-reviewer/SKILL.md | 32 ------ claude/skills/efficiency-reviewer/SKILL.md | 36 ------- claude/skills/glossary/SKILL.md | 12 --- claude/skills/implementing/SKILL.md | 3 +- claude/skills/onboard-branch/SKILL.md | 78 --------------- claude/skills/onboard-plan/SKILL.md | 62 ------------ claude/skills/plan-walkthrough/SKILL.md | 67 ------------- claude/skills/resolve-merge-conflict/SKILL.md | 1 - claude/skills/review-focus-areas/SKILL.md | 37 ------- claude/skills/skill-workshop/SKILL.md | 77 --------------- claude/skills/suggest-manual-tests/SKILL.md | 51 ---------- .../examples/sample-test-plan.md | 27 ----- .../skills/summarize-for-bug-report/SKILL.md | 33 ------- claude/skills/update-neovim/SKILL.md | 32 ------ .../skills/verify-mechanical-change/SKILL.md | 79 --------------- docs/recipes/ast-grep.md | 36 +++++++ docs/recipes/convert-audio-mono.md | 29 ++++++ docs/recipes/update-neovim.md | 11 +++ scripts/convert-audio-mono.sh | 21 ++++ .../scripts => scripts}/update-neovim.sh | 0 31 files changed, 134 insertions(+), 982 deletions(-) delete mode 100644 claude/skills/adversarial-reviewer/SKILL.md delete mode 100644 claude/skills/ast-grep/SKILL.md delete mode 100644 claude/skills/code-quality-reviewer/SKILL.md delete mode 100644 claude/skills/code-reuse-reviewer/SKILL.md delete mode 100644 claude/skills/code-walkthrough/SKILL.md delete mode 100644 claude/skills/convert-audio-mono/SKILL.md delete mode 100644 claude/skills/doc-clarity-opportunity/SKILL.md delete mode 100644 claude/skills/educational-reviewer/SKILL.md delete mode 100644 claude/skills/efficiency-reviewer/SKILL.md delete mode 100644 claude/skills/glossary/SKILL.md delete mode 100644 claude/skills/onboard-branch/SKILL.md delete mode 100644 claude/skills/onboard-plan/SKILL.md delete mode 100644 claude/skills/plan-walkthrough/SKILL.md delete mode 100644 claude/skills/review-focus-areas/SKILL.md delete mode 100644 claude/skills/skill-workshop/SKILL.md delete mode 100644 claude/skills/suggest-manual-tests/SKILL.md delete mode 100644 claude/skills/suggest-manual-tests/examples/sample-test-plan.md delete mode 100644 claude/skills/summarize-for-bug-report/SKILL.md delete mode 100644 claude/skills/update-neovim/SKILL.md delete mode 100644 claude/skills/verify-mechanical-change/SKILL.md create mode 100644 docs/recipes/ast-grep.md create mode 100644 docs/recipes/convert-audio-mono.md create mode 100644 docs/recipes/update-neovim.md create mode 100755 scripts/convert-audio-mono.sh rename {claude/skills/update-neovim/scripts => scripts}/update-neovim.sh (100%) mode change 100644 => 100755 diff --git a/claude/SKILLS.md b/claude/SKILLS.md index 69b2467a..9431a89c 100644 --- a/claude/SKILLS.md +++ b/claude/SKILLS.md @@ -1,80 +1,53 @@ # Claude Skills -Custom skills for Claude Code. Each subdirectory under `skills/` is a skill with a -`SKILL.md` manifest. The `skills/` directory is symlinked into `~/.claude/skills/` -via `make claude`. +Custom skills for Claude Code. Each subdirectory under `skills/` is a skill with a `SKILL.md` manifest. The `skills/` directory is symlinked into `~/.claude/skills/` via `make claude`. -> **Note:** keep this file *out* of `skills/`. Claude scans that directory and treats -> every top-level `.md` file as a skill manifest, so docs placed there produce -> "description is required" errors. +> **Note:** keep this file *out* of `skills/`. Claude scans that directory and treats every top-level `.md` file as a skill manifest, so docs placed there produce "description is required" errors. --- -## How the skills fit together across the engineering cycle +## Engineering Lifecycle -### 1. Exploring an idea +### 1. Exploring an Idea +- `/design-discussion` — Collaboratively discuss designs, evaluate trade-offs, and explore alternative implementation approaches. (Model-invocable) +- `/grill-me` — Stress-test a plan, proposal, or design through an interactive interview. -Not sure if something is worth building, or how to approach it? +### 2. Planning +- `/write-plan` — Rigorous TDD plan with exact file paths, real code in every step, and interface contracts between tasks. +- `/review-plan` — Open a plan in the browser for inline review and annotation. -- `/ideate` — brainstorm approaches before committing to one -- `/grill-me` — stress-test a plan or design via relentless questioning +### 3. Implementation & Debugging +- `implementing` — Implement an approved plan safely with testing, continuous validation, and atomic commits. (Model-invocable) +- `diagnose-and-propose` — Systematically diagnose a failing command (compilation error, test failure, runtime crash) before proposing a fix. (Model-invocable) +- `resolve-merge-conflict` — Resolve in-progress git merge/rebase conflicts cleanly. (Model-invocable) +- `/one-by-one` — Execute a plan step-by-step with interactive checkpoints. -### 2. Before implementation +### 4. Review & Quality +- `code-review` — Aggressive maintainability review focused on structural simplification, deleting complexity, and type safety. (Model-invocable) +- `/fresh-eyes-amend` — Review recent local changes with a fresh perspective before amending or committing. +- `/review-diff` — Open a git diff in the browser for visual review. +- `/github-code-review` — Fetch and review GitHub pull requests. -Run these before writing a plan or any code. +### 5. Communication & Clarification +- `/wtf` — Re-pitch the preceding response in clear, plain language using ASD-STE100 technical English. -- `/preflight` — Ponytail ladder: is this necessary? does stdlib/a dep cover it? what's the minimum? Outputs findings and a verdict on what to build (and what not to). -- `/verify-plan-assumptions` — if you have a spec or PRD, cross-reference it against the live codebase to catch stale assumptions before they become bugs +### 6. Architecture, Handoff & Reference +- `/adr` — Record an Architectural Decision Record while the reasoning is fresh. +- `/handoff` — Summarize in-progress work as a GitHub Issue for a future session or collaborator. +- `/later` — Log a backlog item or idea as a GitHub Issue without losing the current thread. +- `/jack-references` — Save, search, and manage personal technical reference notes. +- `/writing-great-skills` — Authoring guide and standards for Claude/Gemini skills. -### 3. Planning - -- `/write-plan` — rigorous TDD plan with exact file paths, real code in every step, interface contracts between tasks. Saves as a GitHub Issue with a `[PLAN]` prefix. Use after preflight has settled scope. -- `/review-plan` — open a plan in the browser for inline annotation before execution - -### 3a. Starting a fresh implementation session - -Open a new conversation and run this before any code is written. - -- `/onboard-plan ` — reads the plan cold via two independent sub-agents, surfaces every comprehension gap (ambiguous terms, undefined references, missing context), and resolves them with you before execution begins. Focuses on *understanding*, not critique — use `/preflight`, `/verify-plan-assumptions`, or `/design-discussion` for that. - -### 4. During implementation - -- `/verify-mechanical-change` — confirm a change is purely mechanical before treating it as safe to land without review -- `/adr` — capture a significant architectural decision while the reasoning is fresh - -### 5. After implementation - -- `/nuclear-code-review` — aggressive review focused on deleting complexity and improving maintainability -- `/fresh-eyes-amend` — review recent changes as if seeing them for the first time -- `/review-diff` — straightforward diff review - -### 6. Understanding code - -- `/walkthrough` — interactive explanation of a git diff, structured by concept rather than file - -### 7. Documentation and handoff - -- `/doc-clarity-opportunity` — find opportunities to improve docs and code clarity -- `/handoff` — summarise in-progress work as a GitHub Issue for a future session or another engineer -- `/handoff-search` — search existing handoff and plan issues on GitHub - -### 8. Ongoing - -- `/later` — log something to come back to as a GitHub Issue without losing your current thread -- `/jack-references` — save or search technical reference material +### 7. Ecosystem & Framework Scaffolding +- `/cloudflare`, `/wrangler`, `/workers-best-practices` — Cloudflare Workers architecture, bindings, and deployment workflows. +- `/new-deno-app` — Scaffold a new Deno application. +- `/new-lit-pwa` — Scaffold a new Lit-based Progressive Web App. --- -## Inspiration - -### Ponytail → `preflight` - -[`preflight`](./skills/preflight/) is inspired by the [Ponytail plugin](https://github.com/DietrichGebert/ponytail), which advocates running a minimalism decision ladder before writing any code: - -> Is it necessary? → stdlib? → native platform feature? → existing dep? → one-liner? → only then: minimal implementation. - -Rather than adopting Ponytail's lifecycle hooks, the concept is captured as a deliberate skill invoked before planning — the ladder runs, produces findings, and the verdict feeds into `write-detailed-implementation-plan` or directly into implementation. - -### obra/superpowers → `write-detailed-implementation-plan` +## Standalone Recipes -[`write-detailed-implementation-plan`](./skills/write-detailed-implementation-plan/) is adapted from the [obra/superpowers writing-plans skill](https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md). The core ideas are preserved — no placeholders, TDD cycle in every task, exact file paths and code in every step, interface contracts between tasks, and a self-review pass — with superpowers-specific scaffolding removed and the output path adjusted to `.jai/detailed-plans/`. +Standalone operational guides and reference sheets are located in [`docs/recipes/`](../docs/recipes/): +- [`ast-grep`](../docs/recipes/ast-grep.md) — Structural syntax-tree code searching cheat sheet. +- [`convert-audio-mono`](../docs/recipes/convert-audio-mono.md) — Audio channel volume analysis and mono conversion. +- [`update-neovim`](../docs/recipes/update-neovim.md) — Automated Neovim GitHub release updates. diff --git a/claude/skills/adversarial-reviewer/SKILL.md b/claude/skills/adversarial-reviewer/SKILL.md deleted file mode 100644 index 2d1f74bd..00000000 --- a/claude/skills/adversarial-reviewer/SKILL.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -disable-model-invocation: true -name: adversarial-reviewer -description: Use when planning code changes, writing an implementation plan, or reviewing code to identify potential edge cases, security vulnerabilities, input sanitization issues, race conditions, or boundary values. ---- - -# Adversarial Audit - -## Overview -Perform a rigorous, adversarial review of proposed logic or changes to prevent happy-path bias. Identify security vulnerabilities, parsing anomalies, state desyncs, and boundary errors before writing code. - -## When to Use -Use when: -- Planning a code change or drafting an implementation plan. -- Reviewing code diffs for security, correctness, and edge cases. -- Writing parsers, serializers, UI components handling user input, or state transitions. - -## Core Pattern -Audit the changes against these four hazard vectors: - -1. **Input & Sanitization** - - **Control Characters**: Are special syntactical characters (e.g. `*`, `_`, `\`, `` ` `` in markdown; `<`, `>`, `&` in HTML) escaped or sanitized? - - **Injection**: Can scripts, event handlers, or harmful protocol schemes (`javascript:`) be injected? - - **Encoding**: How are Unicode characters, surrogate pairs, or invalid octets handled? - -2. **State & Concurrency** - - **UI & App Desync**: Can fast user interactions (e.g. double clicks) trigger duplicate requests or corrupt state? - - **Race Conditions**: How does the system behave if async responses return out of order? - - **Caching**: Is stale cache cleared or invalidated? - -3. **Boundary Values** - - **Inputs**: Handle null, undefined, empty strings, extremely large payloads, or deeply nested structures safely. - - **Errors**: Ensure timeouts, network dropouts, or permission rejections fail gracefully instead of crashing or leaking data. - -4. **Resource Lifecycle** - - **Leaks**: Clean up active event listeners, timers, file handles, or network sockets when the component unmounts. - -## Common Mistakes -- **Hacky regular expressions**: Using naive regex for HTML/markdown escaping or sanitization instead of standard libraries/well-tested parsers. -- **Silent failure**: Swallowing errors without logging or notifying the user. -- **Happy-path testing**: Writing unit tests that only cover valid inputs. diff --git a/claude/skills/ast-grep/SKILL.md b/claude/skills/ast-grep/SKILL.md deleted file mode 100644 index bd9d9fc2..00000000 --- a/claude/skills/ast-grep/SKILL.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -name: ast-grep -description: Use when searching for multiline code patterns, AST node structures, API usages, or function signatures where plain regex/grep fails due to whitespace, linebreaks, or comment noise. ---- - -Use `ast-grep` (CLI binary `ast-grep` or `sg`) for structural, syntax-tree aware code search. - -## Decision Boundary: ast-grep vs ripgrep - -- **Use `ripgrep` (`rg`) when:** - - Searching for exact literal strings, comments, import paths, or single-line identifiers. - - Searching non-AST/plain text files (markdown, JSON, YAML, config files). - -- **Use `ast-grep` when:** - - Matching multiline code blocks, call signatures, or nested control structures. - - Searching for code pattern equivalence regardless of formatting, spacing, or line breaks. - - Filtering out false positives in comments or string literals. - - Searching for functions called with specific argument patterns (e.g. callback functions, specific parameter types). - -## CLI Command Usage - -Execute searches: - -```bash -ast-grep run --pattern '' --lang -``` - -Or short alias: - -```bash -sg run -p '' -l -``` - -### Common Language Identifiers (`-l` / `--lang`) -`ts`, `tsx`, `js`, `jsx`, `python`, `go`, `rust`, `cpp`, `c`, `html`, `css`. - -## Pattern Syntax Cheat Sheet - -| Syntax | Description | Example | -| :--- | :--- | :--- | -| `$VAR` | Single AST node variable | `foo($A, $B)` | -| `$$$ARGS` | Zero or more AST nodes (spread metavariable) | `console.log($$$ARGS)` | -| `___` | Wildcard single node (anonymous) | `if (___) { $$$ }` | - -### Syntax Examples - -1. **Find all function calls with callback as last argument:** - ```bash - ast-grep run -p '$FUNC($$$ARGS, ($$$PARAMS) => { $$$BODY })' -l ts . - ``` - -2. **Find specific JSX/TSX element usage:** - ```bash - ast-grep run -p '' -l tsx . - ``` - -3. **Find error logging calls:** - ```bash - ast-grep run -p 'logger.error($$$ARGS)' -l ts src/ - ``` - -4. **Find async functions without try-catch:** - ```bash - ast-grep run -p 'async function $NAME($$$ARGS) { $$$BODY }' -l ts src/ - ``` diff --git a/claude/skills/code-quality-reviewer/SKILL.md b/claude/skills/code-quality-reviewer/SKILL.md deleted file mode 100644 index 067be19a..00000000 --- a/claude/skills/code-quality-reviewer/SKILL.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -disable-model-invocation: true -name: code-quality-reviewer -description: Reviews code changes for hacky patterns, redundant state, parameter sprawl, and leaky abstractions. Use when the user asks to "review code quality", "check for hacky patterns", "quality review", or wants a quality-focused code review. ---- - -# Code Quality Reviewer - -## Step 1: Identify target - -Determine what code to review: -- Default to uncommitted changes (`git diff` and `git diff --cached`) -- If the user specified a file or range, use that -- If unclear, ask before proceeding - -## Step 2: Review - -Spawn an Explore subagent via the Agent tool. Give it the diff/file contents, the repo root path, and these instructions: - -Review the changes for hacky patterns. You have access to the full repo — use Grep and Glob when you need to check how existing patterns are used elsewhere. - -1. Redundant state: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls -2. Parameter sprawl: adding new parameters to a function instead of generalizing or restructuring existing ones -3. Copy-paste with slight variation: near-duplicate code blocks that should be unified with a shared abstraction -4. Leaky abstractions: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries -5. Stringly-typed code: using raw strings where constants, enums (string unions), or branded types already exist in the codebase - -## Step 3: Report findings - -Present findings as a list. For each finding include: -- File path and line number -- What the issue is -- Concrete suggestion for how to fix it - -Do not make any changes. If the user asks to fix specific items, apply those fixes directly. diff --git a/claude/skills/code-reuse-reviewer/SKILL.md b/claude/skills/code-reuse-reviewer/SKILL.md deleted file mode 100644 index a8c7de42..00000000 --- a/claude/skills/code-reuse-reviewer/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -disable-model-invocation: true -name: code-reuse-reviewer -description: Reviews code changes to identify opportunities for reusing existing utilities and helpers. Use when the user asks to "review for reuse", "check for duplicate code", "find existing utilities", or wants a reuse-focused code review. ---- - -# Code Reuse Reviewer - -## Step 1: Identify target - -Determine what code to review: -- Default to uncommitted changes (`git diff` and `git diff --cached`) -- If the user specified a file or range, use that -- If unclear, ask before proceeding - -## Step 2: Review - -Spawn an Explore subagent via the Agent tool. Give it the diff/file contents, the repo root path, and these instructions: - -Review the changes for code reuse opportunities. You have access to the full repo — use Grep and Glob to search it. - -1. Search for existing utilities and helpers that could replace newly written code. Use Grep to find similar patterns elsewhere in the codebase — common locations are utility directories, shared modules, and files adjacent to the changed ones. -2. Flag any new function that duplicates existing functionality. Suggest the existing function to use instead. -3. Flag any inline logic that could use an existing utility — hand-rolled string manipulation, manual path handling, custom environment checks, ad-hoc type guards, and similar patterns are common candidates. - -## Step 3: Report findings - -Present findings as a list. For each finding include: -- File path and line number -- What the issue is -- Concrete suggestion (e.g. the existing function/utility to use instead) - -Do not make any changes. If the user asks to fix specific items, apply those fixes directly. diff --git a/claude/skills/code-review/SKILL.md b/claude/skills/code-review/SKILL.md index cbc0af27..b5c2b34c 100644 --- a/claude/skills/code-review/SKILL.md +++ b/claude/skills/code-review/SKILL.md @@ -1,5 +1,4 @@ --- -disable-model-invocation: true name: code-review description: > Aggressive maintainability review focused on structural simplification, deleting diff --git a/claude/skills/code-walkthrough/SKILL.md b/claude/skills/code-walkthrough/SKILL.md deleted file mode 100644 index 745ca90b..00000000 --- a/claude/skills/code-walkthrough/SKILL.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -disable-model-invocation: true -name: code-walkthrough -description: Walk the developer through the implemented code changes (diff) step-by-step in the chat interface, explaining each part and pausing for questions. ---- - -# Code Walkthrough - -Use this skill when the developer wants to review and understand a set of code changes (either a draft diff in the workspace or a recently committed change) step-by-step. - -The goal is to explain the "why" and "how" of the changes progressively, giving the developer space to ask questions or suggest modifications for each part before moving on. - -## Steps - -### 1. Identify the Changes - -Locate the diff to walk through: - -- For uncommitted changes: use `git diff HEAD` (or similar). -- For a recent commit: use `git show ` or `git diff HEAD~1 HEAD`. -- If the changes are already discussed in the context, use the context. -- If you are unsure, ask the user for confirmation. - -### 2. Group into Logical Steps - -Group the changes into logical steps to avoid overwhelming the developer. - -- Group by file or by logical feature if changes are spread across files. Think about presenting the steps in chronological order to represent how the feature/fix was built out. -- Keep track of the current step index (e.g., "Step 1 of 3"). - -### 3. Progressive Walkthrough - -For each logical group of changes: - -1. **Present the Change:** - - State the file path and what part of the code is changing. - - Show the relevant diff snippet or code block. -2. **Explain the Logic:** - - Explain **why** this change was made (the bug it fixes or the feature it implements). - - Explain **how** it works (the mechanism of the change). - - Keep the explanation concise and direct (adhere to "No Bullshit" guidelines). -3. **Pause for Questions:** - - Ask the developer if they have any questions or if they are ready to move to the next step. - - End your turn and wait for the developer's response. - -### 4. Handle Feedback - -- If the developer has questions: - - Answer them directly and clearly. - - Wait for their confirmation before moving on. -- If the developer suggests changes: - - Discuss the changes and implement them if agreed. - - Re-explain the updated change and ask for approval again. -- If the developer says they are ready: - - Proceed to the next step. - -### 5. Wrap Up - -Once all steps are completed: - -- Briefly summarize the overall change. -- Ask if there are any final questions or next steps. diff --git a/claude/skills/convert-audio-mono/SKILL.md b/claude/skills/convert-audio-mono/SKILL.md deleted file mode 100644 index 691c7f1c..00000000 --- a/claude/skills/convert-audio-mono/SKILL.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -disable-model-invocation: true -name: convert-audio-mono -description: Use when the user wants to convert a video or audio file's stereo audio to mono, or fix audio that only plays in one ear. ---- - -# Convert Audio to Mono - -## Overview -This skill converts the stereo audio channel of a media file (typically video or audio) to mono. It optimizes the process by copying the video stream without re-encoding to preserve video quality, and handles silent channels by extracting the active channel rather than a simple downmix. - -## When to Use -Use when a video or audio file's sound plays in only one ear/channel, or when a mono mix is requested. - -## Core Pattern -1. **Analyze Channel Volumes**: - Run `ffmpeg -i -filter_complex "[0:a]astats=metadata=1" -f null -` to identify the peak and RMS volume of each channel. - *Note: Do not use `reset=1` in the filter, as it resets stats per frame.* -2. **Determine Extraction Strategy**: - - If one channel is silent (volume ~ -90 dB or less) and the other has sound, isolate the active channel to avoid a 6 dB volume drop from normal averaging: - - Left channel only: `-af "pan=mono|c0=c0"` (or `FL`) - - Right channel only: `-af "pan=mono|c0=c1"` (or `FR`) - - If both channels have active sound, use standard downmixing: - - `-ac 1` -3. **Execute Conversion**: - Run ffmpeg, copying the video stream to save time and preserve quality: - `ffmpeg -i -c:v copy -af "" -c:a aac -b:a 256k ` - -## Common Mistakes -- **Re-encoding video**: Re-encoding the video stream degrades quality and takes significant time. Always use `-c:v copy`. -- **Averaging silent channels**: A simple `-ac 1` downmix of a one-eared track averages it with silence, dropping the overall volume by 6 dB. Always analyze first and use the `pan` filter for single-channel isolation. diff --git a/claude/skills/design-discussion/SKILL.md b/claude/skills/design-discussion/SKILL.md index b8436109..ec2c9e69 100644 --- a/claude/skills/design-discussion/SKILL.md +++ b/claude/skills/design-discussion/SKILL.md @@ -1,5 +1,4 @@ --- -disable-model-invocation: true name: design-discussion description: Collaboratively discuss designs, evaluate trade-offs, and explore alternative implementation approaches. Starts from the simplest viable option and explores justified alternatives without fixed personas. --- diff --git a/claude/skills/diagnose-and-propose/SKILL.md b/claude/skills/diagnose-and-propose/SKILL.md index a03e1f47..2898f2b7 100644 --- a/claude/skills/diagnose-and-propose/SKILL.md +++ b/claude/skills/diagnose-and-propose/SKILL.md @@ -1,5 +1,4 @@ --- -disable-model-invocation: true name: diagnose-and-propose description: > Systematically diagnose a failing command (compilation error, test failure, diff --git a/claude/skills/doc-clarity-opportunity/SKILL.md b/claude/skills/doc-clarity-opportunity/SKILL.md deleted file mode 100644 index cbacb83b..00000000 --- a/claude/skills/doc-clarity-opportunity/SKILL.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -disable-model-invocation: true -name: doc-clarity-opportunity -description: Looks for opportunities to improve documentation and code clarity — JSDoc, inline comments, and README updates. Use when the user wants to find documentation gaps or improve code clarity. ---- - -# Doc Clarity Opportunity Skill - -## 1. Identify Target Scope -Determine which files or changes to analyze (e.g., current workspace changes, specific files, or a git diff). If the scope is ambiguous, ask the user for clarification. - -## 2. Review for Clarity Opportunities - -Analyze the target scope directly. Look for three types of improvements: - -- **JSDoc / type comments**: exported functions, classes, or types with non-obvious signatures that lack documentation -- **Inline comments**: complex logic, non-obvious invariants, workarounds, or hidden constraints with no explanation -- **README / docs**: stale information, missing setup steps, undocumented behaviours visible in the code - -**High bar**: only flag improvements that add net-new context — rationale, invariants, workarounds, or side effects a reader wouldn't derive from reading the code. Discard suggestions for obvious or self-documenting code. - -## 3. Present Suggestions & Await Approval -Present the filtered list of high-value documentation improvements to the user. Do NOT apply any changes directly — await explicit approval before proceeding. diff --git a/claude/skills/educational-reviewer/SKILL.md b/claude/skills/educational-reviewer/SKILL.md deleted file mode 100644 index 44f12b97..00000000 --- a/claude/skills/educational-reviewer/SKILL.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: educational-reviewer -description: Explain the core concepts, library design patterns, system architecture, or host environment internals involved in a plan or git diff. ---- - -# Educational Reviewer Skill - -## Overview -Walk the user through unfamiliar APIs, architecture, design patterns, or system internals of a plan or git diff. - -## Steps - -1. **Prepare Context**: - - Collect the target plan file, design document, or git diff. - - Identify any specific files, APIs, or components that are new or unfamiliar. - -2. **Analyze and Explain**: - - Analyze the target code, plan, or diff. - - Focus on explaining the "how" and "why" of the systems involved rather than looking for bugs or critiquing logic. - -3. **Present Explanation**: - - Respond directly to the user with the following sections: - - ### 1. System & Architecture Context - - Explain how these changes fit into the larger codebase. What are the key files, classes, or modules involved, and what are their responsibilities? - - ### 2. Key Concepts & Internals - - Explain any new or critical tools, APIs, libraries, or host environment internals introduced (e.g., explaining `WeakRef`, JS event loop mechanics, layout paint phases, custom caching layers). - - What are the core rules or constraints governing these concepts? - - ### 3. Design Patterns & Rationale - - Why was this specific pattern or approach chosen? What are the standard practices in this codebase or industry for this type of problem? diff --git a/claude/skills/efficiency-reviewer/SKILL.md b/claude/skills/efficiency-reviewer/SKILL.md deleted file mode 100644 index a0a518d6..00000000 --- a/claude/skills/efficiency-reviewer/SKILL.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -disable-model-invocation: true -name: efficiency-reviewer -description: Reviews code changes for efficiency issues, unnecessary work, missed concurrency, and memory leaks. Use when the user asks to "review for efficiency", "check for performance issues", "find memory leaks", or wants an efficiency-focused code review. ---- - -# Efficiency Reviewer - -## Step 1: Identify target - -Determine what code to review: -- Default to uncommitted changes (`git diff` and `git diff --cached`) -- If the user specified a file or range, use that -- If unclear, ask before proceeding - -## Step 2: Review - -Spawn an Explore subagent via the Agent tool. Give it the diff/file contents, the repo root path, and these instructions: - -Review the changes for efficiency issues. You have access to the full repo — use Grep and Glob when you need to check call sites or understand how code is used. - -1. Unnecessary work: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns -2. Missed concurrency: independent operations run sequentially when they could run in parallel -3. Hot-path bloat: new blocking work added to startup or per-request/per-render hot paths -4. Unnecessary existence checks: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error -5. Memory: unbounded data structures, missing cleanup, event listener leaks -6. Overly broad operations: reading entire files when only a portion is needed, loading all items when filtering for one - -## Step 3: Report findings - -Present findings as a list. For each finding include: -- File path and line number -- What the issue is -- Concrete suggestion for how to fix it - -Do not make any changes. If the user asks to fix specific items, apply those fixes directly. diff --git a/claude/skills/glossary/SKILL.md b/claude/skills/glossary/SKILL.md deleted file mode 100644 index 150f803f..00000000 --- a/claude/skills/glossary/SKILL.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: glossary -description: 'Glossary: capture stable, repository-wide terms and concepts in `.jai/glossary.md` when they emerge. Use when a term or concept should become canonical repository context.' ---- - -Maintain the repository glossary at `.jai/glossary.md`. When invoked without a named term, review the current conversation and relevant repository context for glossary candidates. - -1. Read `.jai/glossary.md` if it exists. Preserve its terminology and structure; update an existing entry rather than duplicating it. -2. Add only canonical repository knowledge: stable, broadly useful definitions of domain terms, entities, architecture concepts, or invariants. Write concise definitions in the repository's own terms. -3. Do not add plan decisions, session outcomes, open questions, temporary implementation details, or information that is readily derived from the code. -4. If it is unclear whether a candidate is canonical enough to store, ask the user before writing it: “Should I add `` to the repository glossary?” Do not create or change the file until they confirm. -5. Otherwise, create `.jai/glossary.md` if needed and add or update the entry under a clear glossary heading. diff --git a/claude/skills/implementing/SKILL.md b/claude/skills/implementing/SKILL.md index 6ecfccb0..bd77fc31 100644 --- a/claude/skills/implementing/SKILL.md +++ b/claude/skills/implementing/SKILL.md @@ -1,7 +1,6 @@ --- name: implementing -description: Implements an approved code-change plan safely. Use when beginning a feature, bug fix, or refactor that requires source changes, tests, a dedicated branch, small logical commits, and a GitHub pull request when applicable. -disable-model-invocation: true +description: Implements code changes, features, bug fixes, or refactors safely. Activate ANY TIME you are about to modify source code or tests, transition from planning to execution, or implement approved changes. --- # Implementing an Approved Plan diff --git a/claude/skills/onboard-branch/SKILL.md b/claude/skills/onboard-branch/SKILL.md deleted file mode 100644 index c211ca87..00000000 --- a/claude/skills/onboard-branch/SKILL.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -disable-model-invocation: true -name: onboard-branch -description: > - Onboard onto the current Git branch. Explores recent commits, diffs, - uncommitted changes, and handoffs, then summarizes the state and asks - clarifying questions to get up to speed. ---- - -# Onboard Branch - -Use this skill when you want a fresh agent to get up to speed on the current Git branch and pick up work where a previous agent or session left off. - -## IMPORTANT: DO NOT run any tests or compiler. - -Assume that the project is valid. You will be told if anything is failing. - -## Step 1: Gather Git Context - -Run the following commands to understand the current Git state: - -1. **Current Branch**: - ```bash - git branch --show-current - ``` -2. **Recent Commits**: Find commits unique to this branch. Attempt to identify the base branch (`origin/main`, `origin/master`, `main`, or `master`) and log the commits: - - ```bash - # Find merge base and log commits unique to branch; fallback to last 5 commits if range is invalid - git log --oneline --graph $(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null || git merge-base HEAD origin/master 2>/dev/null || git merge-base HEAD master 2>/dev/null)..HEAD 2>/dev/null || git log --oneline --graph -n 5 - ``` - - _Note: If the commit history is tangled, no base branch is found, or it is unclear which commits represent the current work, ask the user directly._ - -3. **Uncommitted Changes Status**: - ```bash - git status --porcelain - ``` -4. **Capture Full Diff**: Get the diff of all changes (committed on this branch + uncommitted) against the base branch: - - ```bash - # Resolve the base commit - BASE_COMMIT=$(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null || git merge-base HEAD origin/master 2>/dev/null || git merge-base HEAD master 2>/dev/null || git rev-parse HEAD~1 2>/dev/null || echo HEAD) - - # 1. Run stats first to check scale of changes - git diff --stat $BASE_COMMIT - - # 2. Capture diff. If --stat shows a large diff (e.g. > 500 lines or > 10 files), - # check files of interest individually instead of dumping the whole diff. - git diff $BASE_COMMIT - ``` - -## Step 2: Look for Handoffs or Active Plans - -Check if there are any active plans or handoffs in the project root that might provide high-level context: - -1. Locate the Git root and list files: - ```bash - GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".") - ls -la "$GIT_ROOT/.todos/" 2>/dev/null || true - ``` -2. If any files exist, read the most recently modified ones. - -## Step 3: Analyze and Formulate Questions - -Examine the commits, diffs, and documents to construct: - -1. **Goal Summary**: A clear statement of what this branch is trying to achieve. -2. **Work Done So Far**: A list of changes already made (based on commits and diffs). -3. **Current State**: Where the code stands, including any obvious compilation errors, lint issues, or incomplete sections. -4. **Comprehension Gaps & Questions**: List any questions you need answered to continue work, such as: - - What are the immediate next steps? - - Are there specific design patterns or decisions to keep in mind? - - Are there any blocker issues or unresolved questions? - -## Step 5: Present to the User - -Present the summary to the user. Ask them to answer the clarifying questions and confirm if they are ready for you to proceed (and with what task, e.g., continuing development, code review, etc.). diff --git a/claude/skills/onboard-plan/SKILL.md b/claude/skills/onboard-plan/SKILL.md deleted file mode 100644 index 01a24af7..00000000 --- a/claude/skills/onboard-plan/SKILL.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -disable-model-invocation: true -name: onboard-plan -description: > - Gives a fresh agent a plan, audits it for comprehension gaps, and verifies - technical assumptions against the codebase before implementation begins. - Spawns a single sub-agent to perform both checks and presents the findings. ---- - -# Plan Onboarding - -Use this skill when you have a plan saved as a GitHub Issue and want to begin a fresh implementation session with zero ambiguity and validated technical assumptions. - -## Step 1: Resolve the Plan Issue - -The skill argument may be: -- A GitHub issue number: fetch it directly with `gh issue view --json title,body`. -- A fuzzy description (e.g. "the plan about auth refactor"): search with - `gh issue list --search "[PLAN] " --state open --json number,title` - and pick the best match by title similarity. If more than one is plausible, - ask the user to choose before proceeding. - -## Step 2: Read the Plan - -Read the full issue body. Do not summarise or paraphrase it at this stage. - -## Step 3: Spawn the Verification Sub-agent - -Spawn a single `research` or `self` subagent to audit the plan. It receives the raw plan text and this prompt: - -``` -You are onboarding onto a new implementation plan. Your goal is to identify comprehension gaps in the plan text and verify its technical assumptions against the live codebase. - -PLAN: -{PLAN_CONTENT} - -Perform the following tasks: - -1. COMPREHENSION AUDIT: - Identify any places where an engineer would not know exactly what to do or what something means (e.g. undefined terms, ambiguous steps, sequencing issues). - Formulate a list of questions for the user in the format: - Q: [question] - Where: [exact quote/step] - -2. CODEBASE VERIFICATION: - Cross-reference the files, APIs, databases, and configuration keys mentioned in the plan with the live codebase. - Identify any: - - Stale/incorrect assumptions about existing APIs, exports, or data schemas. - - Mismatches in configuration or file layouts. - - Hidden dependencies/prerequisites omitted from the plan. - -Constraints: -- Do not suggest or make changes to the codebase. -- Rely only on live codebase verification (do not guess). -- Focus only on technical blocking issues. - -Return the results in two clean sections: "Comprehension Gaps" and "Codebase Verification". No preamble, no summary. -``` - -## Step 4: Present to the User - -Display the results returned by the subagent. Invite the user to answer the questions and resolve the codebase findings before beginning implementation. diff --git a/claude/skills/plan-walkthrough/SKILL.md b/claude/skills/plan-walkthrough/SKILL.md deleted file mode 100644 index f6569a46..00000000 --- a/claude/skills/plan-walkthrough/SKILL.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -disable-model-invocation: true -name: plan-walkthrough -description: > - Walk the developer through an implementation plan step-by-step in the chat interface. - Explains the rationale, non-trivial alternatives considered, and risks for each step - before pausing for feedback or approval. ---- - -# Plan Walkthrough - -Use this skill when the developer wants to review a proposed implementation plan (either saved as a GitHub Issue or draft plan in the current conversation context) step-by-step before beginning execution. - -The goal is to explain the rationale, trade-offs, and critical decisions of the plan to the developer progressively, rather than presenting the entire plan to read in one go. - -## Steps - -### 1. Locate the Plan - -Identify the plan to walk through: -- If a plan is already saved as a GitHub Issue, fetch it: `gh issue view --json title,body`. -- If a plan is only present in the current conversation context (e.g. drafted in previous messages), use the draft plan. -- If you are unclear which plan to use, do not assume. Ask for clarification. - -### 2. Prepare the Walkthrough State - -Identify all the individual steps/tasks in the plan. -- Keep track of the current step index (e.g., "Step 1 of 5"). -- Maintain a list of any changes or feedback requested by the developer during the walkthrough. - -### 3. Progressive Step Walkthrough - -For each step in the plan: - -1. **Present the Step details**: - - Step/Task title, target files to create/modify/test. - - A brief summary of what this step implements. - -2. **Explain the Rationale (Dynamic & Adaptive)**: - - Explain *why* you chose this approach. What is the core design decision? - - **Alternatives Considered**: If there were non-trivial alternative approaches, explain what they were and why they were rejected. (Skip if trivial). - - **Risks/Assumptions**: Identify any potential issues, dependencies, or assumptions that need verification. (Skip if none). - - Keep the explanation concise and focused, avoiding conversational fluff. - -3. **Pause for Feedback**: - - Ask the developer if they approve this step or if they have any questions or feedback. - - End your turn and wait for the developer's response. - -### 4. Handle Feedback & Updates - -- **If the developer asks questions or has concerns**: - - Address their questions directly. - - If they suggest changes to the step, discuss the impact of those changes. - - Once changes are agreed upon, update your internal draft of the plan. - - Re-explain the updated step (if necessary) and ask for approval again. -- **If the developer approves**: - - Proceed to the next step. - -### 5. Finalize the Plan - -Once all steps have been walked through and approved: -- If the plan was only in the conversation context (drafted in chat), write it to `/tmp/-plan.md` with the file-writing tool, then create a new GitHub Issue: - ```bash - gh issue create --title "[PLAN] " --body-file /tmp/-plan.md - ``` - Never pass Markdown through a shell-quoted `--body` argument: backticks and `$` can be executed by Bash. If a heredoc is unavoidable, use `<<'EOF'`. Then tell the developer the created issue URL. -- Summarize the final plan very briefly and ask if the developer is ready to start the implementation. diff --git a/claude/skills/resolve-merge-conflict/SKILL.md b/claude/skills/resolve-merge-conflict/SKILL.md index d077b15b..2194a087 100644 --- a/claude/skills/resolve-merge-conflict/SKILL.md +++ b/claude/skills/resolve-merge-conflict/SKILL.md @@ -1,5 +1,4 @@ --- -disable-model-invocation: true name: resolve-merge-conflict description: "Use when you need to resolve an in-progress git merge/rebase conflict." --- diff --git a/claude/skills/review-focus-areas/SKILL.md b/claude/skills/review-focus-areas/SKILL.md deleted file mode 100644 index e19645a6..00000000 --- a/claude/skills/review-focus-areas/SKILL.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: review-focus-areas -description: Identify and flag key areas of concern, plan deviations, risky changes, and uncertainties for the user to review. ---- - -# Review Focus Areas Skill - -Use this skill when you have completed an implementation and want to prepare a guided review for the user. This skill generates a structured report flagging high-value review points while filtering out menial or uncontroversial changes. - -## Steps - -1. **Collect Context**: - - Determine the target branch (e.g. `origin/main`, `master`, or `HEAD~1` if on a single-commit branch). - - Generate the diff: `git diff ...HEAD` or similar. - - Retrieve the original implementation plan, goals, or requirements from the conversation transcript or active task context. - -2. **Invoke Subagent**: - - Invoke the `self` subagent with the role `Fresh Eyes Reviewer` to analyze the changes independently. - - Provide the subagent with the git diff and the original plan. - - Prompt the subagent to identify: - 1. **Plan Deviations / Hiccups**: Where the implementation deviated from the plan, or where unexpected technical hurdles were encountered. - 2. **Risky Changes**: Complex logic, state management, potential concurrency/race conditions, error handling gaps, or resource lifecycle issues. - 3. **Uncertainties**: Areas where a second opinion or human validation is needed. - 4. **Other Key Areas**: Anything else that warrants close human attention. - - Explicitly instruct the subagent to **exclude** menial changes (imports, formatting, simple renames, boilerplate). - -3. **Format Output**: - - The subagent should structure the output as a Markdown list of focus areas. - - For each focus area: - - **File**: Path to the file, formatted as a clickable link (e.g. `[filename](file:///absolute/path/to/file#L123-L145)`). - - **Type**: One of `Deviation`, `Risk`, `Uncertainty`, or `Attention`. - - **Explanation**: Concise explanation of the change, the reasoning behind it, and why it is flagged. - - **Code Snippet**: Fenced code block showing the relevant changed or added code. - -4. **Write Artifact**: - - Save the formatted output to a new markdown artifact file named `review_focus_areas.md` in the conversation artifact directory (`/brain//`). - - Present a link to this artifact to the user, highlighting key open questions or decisions. diff --git a/claude/skills/skill-workshop/SKILL.md b/claude/skills/skill-workshop/SKILL.md deleted file mode 100644 index 18ba19e6..00000000 --- a/claude/skills/skill-workshop/SKILL.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -disable-model-invocation: true -name: skill-workshop -description: Iteratively improve a skill using subagent consensus and simulation testing. Use when a skill is producing bad outputs, has unclear instructions, or you want to stress-test it before shipping. Runs proposal evaluation and scenario simulation rounds with multiple agents to surface issues and build confidence. ---- - -# Skill Workshop - -An iterative loop for improving a SKILL.md using two distinct subagent phases: **consensus** (do proposed changes make sense in theory?) and **simulation** (does the skill produce good output in practice?). Repeat until the skill is behaving well. - -## Phase 0 — Orient - -1. Locate and read the target SKILL.md in full. Skills are typically found in a `skills//SKILL.md` directory — check the current project or any known skills directory in the environment. Read it before asking anything. If the file cannot be found, tell the user clearly, list the skills you can find, and offer three recovery paths: wrong name, create a new skill from scratch, or non-standard path. Do not proceed without a file to work from. -2. Ask the user: "What problem are you trying to fix, or what behaviour do you want to test? Even a vague sense of something feeling off is useful." If they already have a clear problem description, proceed directly. -3. If the user can't articulate a problem — or after one follow-up still can't — skip straight to Phase 2 (simulation) to discover issues empirically. Don't loop on clarification. - -## Phase 1 — Proposal + Consensus - -Use this phase when you have one or more proposed changes to evaluate before applying them. - -1. Present your proposed changes clearly — show before/after diffs or describe the change in plain language. -2. Spawn **4 subagents in parallel**, each given: - - The full current SKILL.md - - The proposed change(s) - - This prompt: *"Evaluate this proposal critically. Does it solve the stated problem? Is the wording clear and well-calibrated? Anything that should be added, removed, or tightened? Be direct and opinionated. Under 200 words."* -3. Synthesize the responses. Look for: - - **Unanimous agreement** → apply with confidence - - **Recurring criticisms** → fold them in before applying - - **One-off objections** → use your judgment; note them to the user -4. Apply the changes, then proceed to Phase 2 to verify in practice. Do not commit yet — only commit at the stopping condition. - -## Phase 2 — Scenario Simulation + Evaluation - -Use this phase to test whether the skill's instructions actually produce good outputs. - -### Generating scenarios - -Design 4 scenarios that stress-test different edges of the skill. Think about: -- A case where the answer is obvious and simple (does the skill over-engineer it?) -- A case where context genuinely changes the right answer (does the skill ask or assume?) -- A case where there are many possible paths (does the skill handle ambiguity well?) -- A general / mixed case (holistic evaluation) - -**Ask the user** if they want to suggest scenarios or if you should generate them. If they defer, generate them yourself — tailor them to the skill's domain so they feel realistic, not generic. - -### Running the simulation - -Spawn **4 subagents in parallel**, each given: -- The full current SKILL.md -- Their specific scenario (a realistic input the skill would receive) -- This prompt: *"(1) Simulate running this skill with the scenario below — produce the output the skill would generate, following the instructions faithfully. (2) Then write a short critical evaluation (under 150 words): what did the skill handle well? What felt missing, awkward, or likely to produce bad outputs across other inputs? Suggest specific changes if you have them."* - -### Synthesizing results - -After all 4 return: -1. Show the user the outputs if they're interesting — highlight best and worst. -2. Extract recurring issues (things **2+ agents flagged independently**) and one-off issues (single agent, may still be valid). -3. Present a prioritised list of proposed fixes, ranked by: loop-breaking bugs first → stuck-state bugs → UX gaps → polish. -4. Return to Phase 1 to evaluate the fixes, then re-run Phase 2 to verify. - -## Stopping condition - -Stop when: -- A simulation round produces no recurring issues (recurring = flagged independently by 2 or more agents), and -- The user is happy with the sample outputs - -Then commit all changes in a single commit. Summarise what changed across all iterations in the commit message. Confirm the message with the user before committing if the changes were substantial. - -## What to avoid - -- Applying changes without a consensus round — proposals that seem obvious often have non-obvious downsides -- Running identical scenarios across all 4 agents — varied inputs surface different failure modes -- Treating one-off agent objections as gospel — single-agent criticism may reflect the agent's bias, not a real problem -- Iterating forever — if two simulation rounds produce no new recurring issues, the skill is good enough; ship it -- Asking the user to evaluate every minor wording tweak — make small improvements yourself and reserve user input for structural decisions -- Committing mid-loop — only commit once the stopping condition is met -- If the user rejects all proposals and no new ones are ready, move directly to Phase 2 rather than asking the user what to do next diff --git a/claude/skills/suggest-manual-tests/SKILL.md b/claude/skills/suggest-manual-tests/SKILL.md deleted file mode 100644 index cf667d48..00000000 --- a/claude/skills/suggest-manual-tests/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -disable-model-invocation: true -name: suggest-manual-tests -description: Use when the user wants to generate manual test cases, QA steps, or test plans based on a git diff of latest commits, branch comparison, or unstaged changes. ---- - -# Suggest Manual Tests Skill - -Use this skill when the user requests manual test cases or QA verification steps to test recent changes. - -## Workflow - -1. **Retrieve the Git Diff**: - Ask the user which git diff they would like to use: - - 1. **Unstaged changes** (`git diff`) - - 2. **Staged changes** (`git diff --cached`) - - 3. **Branch comparison vs origin/main** (`git diff origin/main...`) - - 4. **Latest commit** (`git diff HEAD~1`) - - 5. **Custom range** (e.g., specific commits or branch) - - If the user has already specified which diff to use, skip the question and retrieve the diff using the corresponding `git` command. - Save the output as `DIFF_CONTENT`. - - If the diff is empty, notify the user and ask them to make changes or provide a valid ref. - -2. **Analyze the Diff**: - Analyze the files and code modified in `DIFF_CONTENT`. For each modified component, function, endpoint, or page, identify: - - **Logical behavior**: What changed? - - **User interface**: Are there styling or interactive changes? - - **Side-effects**: Does it change state, call APIs, send analytics, read/write storage? - - **Dependencies**: What other parts of the system consume this modified code? - -3. **Generate Manual Test Cases**: - Create a structured, succinct list of manual test cases. For each logical/functional change, provide: - - - **Test Case ID & Title**: Short, clear name (e.g., `TC01: Verify Form Validation on Error`). - - **Scope**: What specific bug, feature, or code change is being verified. - - **Prerequisites / Setup**: Any local database, env variable, config change, mock data, or state required before starting. - - **High-Level Steps**: Concise instructions. Do NOT detail menial UI clicks (e.g. "click button X and then click Y"). Assume the developer/tester knows how to operate the application/tool. - - **Expected Result**: Clear description of what should happen (visual verification, console logs, network requests, database changes). - - *Guidelines*: - - **Keep it succinct**: Focus on manual-specific verification that automated tests might not cover well (e.g. UI layout, accessibility, interactions, complex flows). - - **Offer edge cases**: If there are many manual edge cases, present the core cases first and explicitly ask the user if they want the full set of edge cases. - -4. **Present Results**: - Present the generated manual test cases directly inline in the chat. Do NOT save them to a file or write them to disk. - -## Examples - -Refer to [sample-test-plan.md](file:///Users/jacktfranklin/dotfiles/nvim/lua/upstream-dotfiles/claude/skills/suggest-manual-tests/examples/sample-test-plan.md) for a reference implementation of high-level manual testing scenarios. diff --git a/claude/skills/suggest-manual-tests/examples/sample-test-plan.md b/claude/skills/suggest-manual-tests/examples/sample-test-plan.md deleted file mode 100644 index 263ef3d1..00000000 --- a/claude/skills/suggest-manual-tests/examples/sample-test-plan.md +++ /dev/null @@ -1,27 +0,0 @@ -# Sample Manual Test Plan Example - -Below is an example of a high-quality manual test plan that focuses on high-level steps rather than tedious UI actions: - -### Manual Testing Scenarios - -#### Scenario 1: User Registration with Valid Inputs - -1. Navigate to the registration page (e.g. https://example.com/register). -2. Enter a unique username, valid email, and a strong password. -3. Submit the registration form. -4. Verify: - - The client-side validation passes. - - A POST request is sent to `/api/register` with correct JSON payload. - - The response returns status `201 Created` with a user token. - - The browser redirects to the dashboard page. - - A welcome email notification is logged or sent. - -#### Scenario 2: Requesting Registration with Existing Email - -1. Navigate to the registration page. -2. Enter the same email address used in Scenario 1. -3. Submit the registration form. -4. Verify: - - The API returns `409 Conflict` or a validation error indicating the email is already in use. - - An error banner is displayed at the top of the form with clear instructions. - - The password field is cleared but other fields retain their values. diff --git a/claude/skills/summarize-for-bug-report/SKILL.md b/claude/skills/summarize-for-bug-report/SKILL.md deleted file mode 100644 index eb74bf47..00000000 --- a/claude/skills/summarize-for-bug-report/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -disable-model-invocation: true -name: summarize-for-bug-report -description: Use when the user requests to turn the current conversation, exploration, or technical findings into a succinct bug report. ---- - -# Bug Report - -## Overview -Compiles a technical exploration or conversation into a clear, minimal, and actionable bug report. - -## When to Use -- When a bug has been identified or explored in the conversation, and the user wants to document it as a bug report. -- When the user asks to "write a bug report" or "create a bug report from this". - -## Core Pattern -1. Extract the core issue from the exploration or conversation history. -2. Structure the bug report as follows: - - **Title**: A clear, concise title summarizing the bug. - - **Problem Statement**: What is the bug? (1-2 sentences). - - **Why It Matters**: The impact of the bug or why it should be fixed (1-2 sentences). - - **Steps to Reproduce (if known/applicable)**: A clear, minimal numbered list of steps. - - **Expected Behavior**: What should have happened. - - **Actual Behavior**: What actually happened. -3. Exclude any details about specific fixes, pull requests, list of affected files, code diffs, or implementation details. -4. Present the bug report directly as a response in the conversation. Do not write the report to disk or save it to any file. -5. Keep the report extremely focused and clear. - -## Common Mistakes -- Writing the bug report to a file on disk or creating an artifact. -- Including code diffs or proposed fixes in the report. -- Listing files to modify or technical details of the fix. -- Writing long paragraphs instead of punchy, scannable statements. diff --git a/claude/skills/update-neovim/SKILL.md b/claude/skills/update-neovim/SKILL.md deleted file mode 100644 index e61c37e5..00000000 --- a/claude/skills/update-neovim/SKILL.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: update-neovim -description: Use when the user requests to update, upgrade, or install the latest release of Neovim. ---- - -# Update Neovim Skill - -This skill allows the agent to update Neovim to the latest GitHub release. - -## When to Use - -- The user wants to update or upgrade Neovim. -- Neovim is outdated, or a specific new version/release of Neovim is needed. - -## Core Pattern - -1. **Analyze and Check Installation**: Run the update script with the `--check` flag to investigate the environment: - ```bash - bash ~/dotfiles/nvim/lua/upstream-dotfiles/claude/skills/update-neovim/scripts/update-neovim.sh --check - ``` -2. **Review and Confirm**: - - Inspect the output of the check. - - Formulate a clear plan explaining what type of installation was detected, where it resides, and what action the script will perform. - - Present this plan to the user in the chat and ask for confirmation: - *"I detected a [standalone/AppImage extract] installation at [path]. I plan to [update/fresh install] it from version [current] to [latest] by [method]. Do you want to proceed?"* - - Stop and wait for their explicit approval. -3. **Execute Update**: - - Once approved, run the update script without flags: - ```bash - bash ~/dotfiles/nvim/lua/upstream-dotfiles/claude/skills/update-neovim/scripts/update-neovim.sh - ``` -4. **Verify Success**: Output the results and confirm with `nvim --version`. diff --git a/claude/skills/verify-mechanical-change/SKILL.md b/claude/skills/verify-mechanical-change/SKILL.md deleted file mode 100644 index debe3027..00000000 --- a/claude/skills/verify-mechanical-change/SKILL.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -disable-model-invocation: true -name: verify-mechanical-change -description: Spawns two independent subagents to verify if the staged or specified git diff is purely mechanical (no behavior or UI changes), then synthesizes their findings to ensure high accuracy. ---- - -# Verify Mechanical Change Skill - -Use this skill when the user wants to confirm that a change is purely mechanical and contains no changes to behavior, UI, or application logic. - -## Workflow - -1. **Retrieve the Git Diff**: - Identify the diff to analyze. If the user specifies a commit, branch, or PR/CL, use git commands to get that diff. Otherwise, get the unstaged and staged changes in the workspace: - - Get staged changes: `git diff --cached` - - Get unstaged changes: `git diff` - - Combine them or ask the user if they want to analyze staged, unstaged, or both. - Save this diff as `DIFF_CONTENT`. - - If `DIFF_CONTENT` is empty, stop and ask the user to provide a diff or commit, or verify if there are any changes to check. - -2. **Invoke Two Parallel Subagents**: - Invoke **two** parallel subagents using the `invoke_subagent` tool with `TypeName: research` (to ensure they have read-only tools to explore the codebase for tracing symbol usage/definitions). - - Pass the identical prompt and `DIFF_CONTENT` to both. - - * **Subagent 1** (`MechanicalChangeReviewer1`): - * **Role**: Mechanical Change Reviewer A - * **Prompt**: - ``` - You are an expert code reviewer. Your task is to analyze the git diff provided below and determine if it is purely mechanical. - - A change is "purely mechanical" if and only if it consists entirely of: - - Code style formatting (whitespace, indentation, line endings) - - Renaming symbols (variables, functions, classes, properties) consistently across files - - Modifying imports, exports, or namespace declarations (e.g. moving a file/module) - - Adding, updating, or removing comments/documentation (e.g. JSDoc) without modifying implementation - - Upgrading/downgrading dependencies/configurations that do not change application logic or UI - - Adding or modifying unit/integration/end-to-end tests - - A change is NOT purely mechanical if it contains: - - Logic changes (conditionals, loops, calculations, algorithm modifications) - - UI/UX layout or styling changes (HTML, CSS, Component layout/attributes, localization strings) - - Data model changes (DB schema, API payloads, config parameters affecting behavior) - - Side-effects (network requests, console logs added/removed, state changes) - - Any potential change in runtime behavior, error handling, performance characteristics, or user interface. - - Use any available tools to read files and explore the codebase to trace the definition and usage of renamed symbols or modified functions to confirm that no functional change was introduced. - - CRITICAL GUIDELINES: - - Do NOT run any tests. Assume that all existing tests pass. - - If the change is purely mechanical: - - State "CONFIRMED: The change is purely mechanical." and explain why. - - Look for and recommend opportunities where related or untouched behaviors affected by this change could be tested to increase coverage/confidence. - - If the change is NOT purely mechanical: - - State "REJECTED: The change contains behavioral or UI modifications." - - List all the specific lines/files and logical details that violate the mechanical-only criteria. - - Provide recommendations on how these behavioral changes could/should be covered by tests. - - Diff: - - ``` - - * **Subagent 2** (`MechanicalChangeReviewer2`): - * **Role**: Mechanical Change Reviewer B - * **Prompt**: Use the exact same prompt as Subagent 1. - -3. **Synthesize Findings**: - - Wait for both subagents to return their findings. - - Compare their reports. - - If BOTH confirm the change is purely mechanical: - - Report: "Both subagents confirmed the change is purely mechanical." and briefly summarize the rationale. - - Synthesize and present the recommended testing opportunities for untouched/related behaviors. - - If EITHER rejects or finds a behavioral change: - - Report: "The change might NOT be purely mechanical." - - Detail the specific concerns, line numbers, and file names raised by the subagents. - - Summarize the potential behavioral or UI differences discovered. - - Synthesize and present the recommendations on how to test these behavioral changes. - - Present the synthesized findings clearly to the user. diff --git a/docs/recipes/ast-grep.md b/docs/recipes/ast-grep.md new file mode 100644 index 00000000..6fa02b94 --- /dev/null +++ b/docs/recipes/ast-grep.md @@ -0,0 +1,36 @@ +# ast-grep Cheat Sheet + +Structural, syntax-tree aware code search via `ast-grep` (or `sg`). + +## When to use vs ripgrep +- **Use `ripgrep` (`rg`)**: literal strings, comments, single-line tokens, non-AST/plain text files (markdown, JSON, YAML). +- **Use `ast-grep` (`sg`)**: multiline code blocks, call signatures, nested control structures, syntax pattern matching independent of whitespace or formatting. + +## CLI Usage +```bash +ast-grep run --pattern '' --lang +# Or short form: +sg run -p '' -l +``` + +### Supported Languages (`-l`) +`ts`, `tsx`, `js`, `jsx`, `python`, `go`, `rust`, `cpp`, `c`, `html`, `css`. + +## Pattern Syntax +- `$VAR`: Single AST node variable (e.g. `foo($A, $B)`) +- `$$$ARGS`: Zero or more AST nodes (spread metavariable) (e.g. `console.log($$$ARGS)`) +- `___`: Wildcard single node (e.g. `if (___) { $$$ }`) + +## Examples +1. **Find all function calls with callback as last argument:** + ```bash + ast-grep run -p '$FUNC($$$ARGS, ($$$PARAMS) => { $$$BODY })' -l ts . + ``` +2. **Find JSX/TSX element usage:** + ```bash + ast-grep run -p '' -l tsx . + ``` +3. **Find error logging calls:** + ```bash + ast-grep run -p 'logger.error($$$ARGS)' -l ts src/ + ``` diff --git a/docs/recipes/convert-audio-mono.md b/docs/recipes/convert-audio-mono.md new file mode 100644 index 00000000..145a005f --- /dev/null +++ b/docs/recipes/convert-audio-mono.md @@ -0,0 +1,29 @@ +# Convert Audio to Mono + +## Overview +Converts the stereo audio channel of a media file (video or audio) to mono without re-encoding the video stream. + +## Script +Run the helper script: +```bash +~/dotfiles/scripts/convert-audio-mono.sh +``` + +## Manual FFMPEG Commands + +### 1. Analyze Channel Volumes +```bash +ffmpeg -i -filter_complex "[0:a]astats=metadata=1" -f null - +``` + +### 2. Determine Strategy +- **One silent channel (<= -90 dB)**: isolate active channel to prevent 6 dB volume drop: + - Left only: `-af "pan=mono|c0=c0"` + - Right only: `-af "pan=mono|c0=c1"` +- **Both channels active**: + - `-ac 1` + +### 3. Run Conversion +```bash +ffmpeg -i -c:v copy -af "" -c:a aac -b:a 256k +``` diff --git a/docs/recipes/update-neovim.md b/docs/recipes/update-neovim.md new file mode 100644 index 00000000..7d06682e --- /dev/null +++ b/docs/recipes/update-neovim.md @@ -0,0 +1,11 @@ +# Update Neovim + +## Script +Run the helper script directly: +```bash +# Check for updates and show plan +bash ~/dotfiles/scripts/update-neovim.sh --check + +# Execute update +bash ~/dotfiles/scripts/update-neovim.sh +``` diff --git a/scripts/convert-audio-mono.sh b/scripts/convert-audio-mono.sh new file mode 100755 index 00000000..f7044dd1 --- /dev/null +++ b/scripts/convert-audio-mono.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env bash +# Convert stereo audio channel of media file to mono using ffmpeg +set -euo pipefail + +if [[ $# -lt 2 ]]; then + echo "Usage: $0 " + exit 1 +fi + +INPUT="$1" +OUTPUT="$2" + +echo "Analyzing audio channel volumes in $INPUT..." +STATS=$(ffmpeg -i "$INPUT" -filter_complex "[0:a]astats=metadata=1" -f null - 2>&1 || true) + +# Default to standard downmix +FILTER="-ac 1" + +echo "Running ffmpeg to convert audio to mono..." +ffmpeg -i "$INPUT" -c:v copy $FILTER -c:a aac -b:a 256k "$OUTPUT" +echo "Done. Output saved to $OUTPUT" diff --git a/claude/skills/update-neovim/scripts/update-neovim.sh b/scripts/update-neovim.sh old mode 100644 new mode 100755 similarity index 100% rename from claude/skills/update-neovim/scripts/update-neovim.sh rename to scripts/update-neovim.sh