diff --git a/extras/skills/codemark/SKILL.md b/extras/skills/codemark/SKILL.md index 85e72fd..7f0a2a8 100644 --- a/extras/skills/codemark/SKILL.md +++ b/extras/skills/codemark/SKILL.md @@ -295,7 +295,9 @@ For common query patterns across languages, see: ## Best Practices -- **Target small, specific code**: Prefer single functions over entire classes, specific methods over whole modules. Smaller bookmarks are more resilient to refactoring, easier to understand, and more precise for navigation. A well-chosen function bookmark survives most structural changes, while large class bookmarks often drift when code is reorganized. +- **Target small, specific code**: Prefer single functions over entire classes, specific methods over whole modules. Smaller bookmarks are more resilient to refactoring, easier to understand, and more precise for navigation. +- **Fine-grained execution targeting**: Don't just bookmark containers (classes/functions). Bookmark **execution boundaries** like critical method calls (`call_expression`), authorization gates (`if_statement`), or complex state transitions (`switch`/`match`). +- **Granularity Strategy**: We prefer **more, highly specific bookmarks** over fewer, general ones. For example, if a function performs three critical steps (auth, validation, DB write), it is better to bookmark those three specific lines/nodes than to bookmark the entire function. - Use `--created-by agent` to distinguish your bookmarks from the user's. - Use `--collection ` when creating bookmarks to add them directly to a collection (collections are auto-created if they don't exist). - **Iterative enhancement**: When working with an existing bookmark and discover new context, use `annotate` to add notes without re-parsing the file. Multiple agents can annotate the same bookmark over time. diff --git a/extras/skills/codemark/examples.md b/extras/skills/codemark/examples.md index c606011..efdee03 100644 --- a/extras/skills/codemark/examples.md +++ b/extras/skills/codemark/examples.md @@ -28,6 +28,22 @@ Focus on *why* the code matters and its relationships. Avoid repeating informati codemark add --file src/auth.rs --range 42 --note "Core auth validator. entry point for all signed requests. Relationships: depends on Claims struct." --tag feature:auth --tag role:entrypoint --tag layer:logic --created-by agent ``` +## Targeting Fine-Grained Execution Logic + +Instead of bookmarking the entire function, target the specific execution point where critical actions occur. + +### Bookmark a specific method call inside a function +```bash +# Target the exact line where the database is updated +codemark add-from-query \ + --file src/db/repo.rs \ + --query '(call_expression function: (member_expression property: (property_identifier) @method (#eq? @method "update_user_balance"))) @target' \ + --note "Critical: Database update point for user balances. Relationships: triggered after payment verification." \ + --tag layer:data \ + --tag role:repository \ + --created-by agent +``` + ## Creating Bookmarks with Raw Queries ### 1. Use dry-run to verify query uniqueness diff --git a/extras/skills/codemark/queries/common.md b/extras/skills/codemark/queries/common.md index c01550d..235d0f1 100644 --- a/extras/skills/codemark/queries/common.md +++ b/extras/skills/codemark/queries/common.md @@ -154,16 +154,69 @@ If you're bookmarking code that seems like it will be refactored: ### Strategy: Bookmark Multiple Related Functions -When a function has siblings you also care about, bookmark them explicitly rather than relying on broad queries: +When a function has siblings or internal steps you also care about, bookmark them explicitly. We prefer **more, highly specific bookmarks** over fewer, general ones. ```bash # Bookmark each method individually codemark add-from-query --file src/auth.swift --query '(function_declaration name: (simple_identifier) @name (#eq? @name "validateToken")) @target' --note "Auth validation: validateToken" --tag feature:auth codemark add-from-query --file src/auth.swift --query '(function_declaration name: (simple_identifier) @name (#eq? @name "refreshToken")) @target' --note "Auth validation: refreshToken" --tag feature:auth -codemark add-from-query --file src/auth.swift --query '(function_declaration name: (simple_identifier) @name (#eq? @name "checkPermission")) @target' --note "Auth validation: checkPermission" --tag feature:auth ``` -### Structural Signature Matching +## Targeting Fine-Grained Execution Logic + +Sometimes bookmarking an entire function is too broad. You can target specific execution boundaries, logic gates, and method calls *inside* those functions. + +### 1. Bookmarking Method Calls (`call_expression`) +Instead of bookmarking where a function is defined, bookmark where a critical function is **invoked**. + +```scheme +# Target any execution of `verify_signature` (Rust, TS, Python) +(call_expression + function: (identifier) @func + (#eq? @func "verify_signature")) @target +``` + +```scheme +# Target a specific method call on an object, like `db.commit()` +(call_expression + function: (member_expression + property: (property_identifier) @method + (#eq? @method "commit"))) @target +``` + +### 2. Bookmarking Conditionals (`if_statement`) +Target the exact decision points, such as authorization guards or error handling branches. + +```scheme +# Target an if-statement that checks an "is_admin" variable +(if_statement + condition: (identifier) @cond + (#eq? @cond "is_admin")) @target +``` + +### 3. Bookmarking Comparisons (`binary_expression`) +Identify hardcoded business rules or boundary limits. + +```scheme +# Target anywhere a strict equality check compares against the string "admin" +(binary_expression + operator: "==" + right: (string) @val + (#match? @val "admin")) @target +``` + +### 4. Bookmarking Complex Branching (`switch` / `match`) +Target state machines or reducers by locating `switch_statement` or `match_expression`. + +```scheme +# TS / Go / Swift: Target a switch statement switching on "action.type" +(switch_statement + value: (member_expression + property: (property_identifier) @prop + (#eq? @prop "type"))) @target +``` + +## Structural Signature Matching Instead of matching by name, match by parameter/return types which change less often: diff --git a/extras/skills/codemark/queries/csharp.md b/extras/skills/codemark/queries/csharp.md index 0a36e10..6352ba9 100644 --- a/extras/skills/codemark/queries/csharp.md +++ b/extras/skills/codemark/queries/csharp.md @@ -106,6 +106,37 @@ Any async method: (#eq? @method "InvalidateCache")) @target)) ``` +### Call Expression (Invocation) + +Target where a specific method is invoked: + +```scheme +(invocation_expression + function: (identifier) @func + (#eq? @func "VerifyToken")) @target +``` + +### Switch Statement + +Target complex branching logic: + +```scheme +(switch_statement + expression: (identifier) @val + (#eq? @val "action")) @target +``` + +### If Statement + +Target specific logical decision points: + +```scheme +(if_statement + condition: (parenthesized_expression + (identifier) @cond + (#eq? @cond "IsAdmin"))) @target +``` + ## Module Tagging C# uses `namespace:` with the full C# namespace: diff --git a/extras/skills/codemark/queries/dart.md b/extras/skills/codemark/queries/dart.md index 75389ff..fa8db4c 100644 --- a/extras/skills/codemark/queries/dart.md +++ b/extras/skills/codemark/queries/dart.md @@ -81,6 +81,36 @@ Any async function: (#eq? @method "parseToken")) @target) ``` +### Call Expression (Method Call) + +Target where a specific method is invoked: + +```scheme +(method_invocation + name: (simple_identifier) @method + (#eq? @method "verifyToken")) @target +``` + +### Switch Statement + +Target complex branching logic: + +```scheme +(switch_statement + expression: (identifier) @val + (#eq? @val "action")) @target +``` + +### If Statement + +Target specific logical decision points: + +```scheme +(if_statement + condition: (identifier) @cond + (#eq? @cond "isAdmin")) @target +``` + ## Module Tagging Dart uses `package:` based on the package or library name: diff --git a/extras/skills/codemark/queries/go.md b/extras/skills/codemark/queries/go.md index 42981d1..89537d8 100644 --- a/extras/skills/codemark/queries/go.md +++ b/extras/skills/codemark/queries/go.md @@ -94,6 +94,37 @@ Any exported (capitalized) function: (#eq? @type "string")))) @target ``` +### Call Expression (Function Call) + +Target where a specific function is invoked: + +```scheme +(call_expression + function: (identifier) @func + (#eq? @func "VerifyToken")) @target +``` + +### Switch Statement + +Target complex branching logic: + +```scheme +(switch_statement + value: (identifier) @val + (#eq? @val "action")) @target +``` + +### If Statement + +Target specific logical decision points: + +```scheme +(if_statement + condition: (call_expression + function: (identifier) @func + (#eq? @func "IsAuthorized"))) @target +``` + ## Module Tagging Go uses `package:` with the full package path relative to module root (using dots): diff --git a/extras/skills/codemark/queries/java.md b/extras/skills/codemark/queries/java.md index 6d9b374..601e1dd 100644 --- a/extras/skills/codemark/queries/java.md +++ b/extras/skills/codemark/queries/java.md @@ -110,6 +110,38 @@ Any static method: (#eq? @type "String")))) @target ``` +### Call Expression (Method Call) + +Target where a specific method is invoked: + +```scheme +(method_invocation + name: (identifier) @method + (#eq? @method "verifyToken")) @target +``` + +### Switch Statement + +Target complex branching logic: + +```scheme +(switch_statement + condition: (parenthesized_expression + (identifier) @val + (#eq? @val "action"))) @target +``` + +### If Statement + +Target specific logical decision points: + +```scheme +(if_statement + condition: (parenthesized_expression + (identifier) @cond + (#eq? @cond "isAdmin"))) @target +``` + ## Module Tagging Java uses `package:` with the full Java package name (dot notation): diff --git a/extras/skills/codemark/queries/python.md b/extras/skills/codemark/queries/python.md index 3a45dd9..b2f9446 100644 --- a/extras/skills/codemark/queries/python.md +++ b/extras/skills/codemark/queries/python.md @@ -74,6 +74,37 @@ Decorators are automatically skipped; this targets the function itself: (#eq? @method "validate_token")) @target)) ``` +### Call Expression (Function Call) + +Target where a specific function is invoked: + +```scheme +(call_expression + function: (identifier) @func + (#eq? @func "verify_token")) @target +``` + +### Match Statement (Python 3.10+) + +Target complex branching logic: + +```scheme +(match_statement + subject: (identifier) @val + (#eq? @val "event")) @target +``` + +### If Statement + +Target specific logical decision points: + +```scheme +(if_statement + condition: (call_expression + function: (identifier) @func + (#eq? @func "is_authorized"))) @target +``` + ### Function with Specific Parameters Function with a specific parameter name: diff --git a/extras/skills/codemark/queries/rust.md b/extras/skills/codemark/queries/rust.md index 5903530..bb312a2 100644 --- a/extras/skills/codemark/queries/rust.md +++ b/extras/skills/codemark/queries/rust.md @@ -107,6 +107,37 @@ Any async function: (async)) @target ``` +### Call Expression (Function Call) + +Target where a specific function is invoked: + +```scheme +(call_expression + function: (identifier) @func + (#eq? @func "verify_token")) @target +``` + +### Match Expression + +Target complex branching logic: + +```scheme +(match_expression + value: (identifier) @val + (#eq? @val "event")) @target +``` + +### If Statement + +Target specific logical decision points: + +```scheme +(if_statement + condition: (call_expression + function: (identifier) @func + (#eq? @func "is_authorized"))) @target +``` + ### Function with Specific Signature Function taking String and returning Claims: diff --git a/extras/skills/codemark/queries/swift.md b/extras/skills/codemark/queries/swift.md index e085e47..49d16c5 100644 --- a/extras/skills/codemark/queries/swift.md +++ b/extras/skills/codemark/queries/swift.md @@ -108,6 +108,38 @@ Any async function: (#eq? @effect "async")) @target ``` +### Call Expression (Function Call) + +Target where a specific function is invoked: + +```scheme +(call_expression + function: (navigation_expression + (navigation_suffix + (simple_identifier) @method + (#eq? @method "verifyToken")))) @target +``` + +### Switch Statement + +Target complex branching logic: + +```scheme +(switch_statement + expr: (identifier) @val + (#eq? @val "action")) @target +``` + +### If Statement + +Target specific logical decision points: + +```scheme +(if_statement + condition: (identifier) @cond + (#eq? @cond "isAdmin")) @target +``` + ### Function with Specific Signature Function taking String and returning Claims: diff --git a/extras/skills/codemark/queries/typescript.md b/extras/skills/codemark/queries/typescript.md index 9ce8341..93629a9 100644 --- a/extras/skills/codemark/queries/typescript.md +++ b/extras/skills/codemark/queries/typescript.md @@ -96,6 +96,37 @@ Any async function: async: "async") @target ``` +### Call Expression (Function Call) + +Target where a specific function is invoked: + +```scheme +(call_expression + function: (identifier) @func + (#eq? @func "verifyToken")) @target +``` + +### Switch Statement + +Target complex branching logic: + +```scheme +(switch_statement + discriminant: (identifier) @val + (#eq? @val "action")) @target +``` + +### If Statement + +Target specific logical decision points: + +```scheme +(if_statement + condition: (parenthesized_expression + (identifier) @cond + (#eq? @cond "isAdmin"))) @target +``` + ### Class Property ```scheme diff --git a/extras/skills/codemark/templates.md b/extras/skills/codemark/templates.md index d03f236..ea9781e 100644 --- a/extras/skills/codemark/templates.md +++ b/extras/skills/codemark/templates.md @@ -9,6 +9,9 @@ The `--note` should be concise and focus on the purpose of the code. **Do not re - ****: The primary function or role of this code (e.g., Auth Validator, Configuration, Entry point). - ****: Why this piece of code is important or what it does. +**Tip for Fine-Grained Bookmarks:** When targeting internal nodes like `call_expression` or `if_statement`, use the note to explain the *specific execution boundary* being marked. +*Example:* `Execution Boundary: Exact point where the JWT signature is verified before proceeding to claims extraction.` + *Example:* `Auth Validator: Handles all JWT verification for incoming requests.` ## 2. Context Template (Extended)