Improve codemark skill with fine-grained execution logic queries

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 <name>` 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.

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

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:
 

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:<name>` with the full C# namespace:

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:<name>` based on the package or library name:

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:<path>` with the full package path relative to module root (using dots):

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:<name>` with the full Java package name (dot notation):

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:

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:

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: