slicing-code-context

Slicing Code Context

Use the capable coordinator to choose relevant code. Give an external/local worker only the task and a deterministic Trailmark slice packet, then verify its response. The bundled Claude agent is a bounded-source fallback, not a strict empty-context process: Claude Code also injects repository instructions, git status, environment data, and a composed delegation prompt.

When to Use

• Offload explanation, classification, review, or mechanical edit proposals for a function or class
• Trace callers, callees, shortest call paths, or entrypoint-to-target paths within a small context window
• Focus a local or lower-cost model on explicit source lines and their graph neighborhood
• Keep repository access and final judgment with the coordinator

When NOT to Use

• The worker must explore the repository or discover its own scope
• Runtime behavior, generated code, macros, or dynamic dispatch dominate what Trailmark can see
• The anchor alone cannot fit and no meaningful line range is known
• The task requires direct worker edits; workers may only propose changes
• A small file can be read safely without graph selection or delegation

Rationalizations to Reject

Workflow

1. Define the worker task and anchors

Keep the worker task concrete and independently checkable. Infer an exact symbol or line range from the user's request. If a name is ambiguous, run the slicer once, show its candidate IDs, and choose from evidence; never pick the first match.

Choose a mode:

Use --line-range FILE:START-END when only part of a large unit is relevant. Line-range paths must be relative to the target root.

2. Build the packet

uv run "{baseDir}/scripts/build_slice_packet.py" \
  --target-dir "{targetDir}" \
  --symbol 'exact-node-id' \
  --mode neighborhood \
  --depth 1 \
  --budget-tokens 8192 \
  --language auto \
  --format json

Replace {targetDir} with the source-tree root chosen for the task. If Claude Code leaves the repository-standard {baseDir} placeholder literal, use "${CLAUDE_SKILL_DIR}/scripts/build_slice_packet.py" for the script path.

The PEP 723 script requires Python 3.12+ and resolves Trailmark 0.5.x with uv. If execution fails, report the error. Do not substitute hand-selected source or an unbounded repository dump.

Before delegation, verify:

• budget.used_estimated_tokens <= budget.limit_estimated_tokens
• Every slice is inside the target root and has a live line range
• The packet includes the intended anchor and mode
• Omissions and uncertain edges are acceptable for the task

The 8K default bounds only an estimated rendered packet. It does not prove that the worker's full prompt fits a model context window: reserve capacity for the task, system/ambient context, and output, and lower the packet limit when needed.

For the full packet and worker response contracts, read references/slice-packet.md.

3. Delegate without leaking context

Use the host's subagent mechanism and the user's configured worker/model selector. Prefer the plugin agent trailmark:code-slice-worker when the host supports plugin agents; it defaults to Haiku and has no repository-reading or mutation tools. Do not claim that Claude's model field routes to an arbitrary local runtime; local hosting and transport are external configuration.

Only an external adapter can guarantee a task-and-packet-only prompt. Claude custom agents also receive unavoidable startup context from Claude Code. Do not deliberately add conversation history or source beyond the packet to either path.

Send exactly:

1. The concrete task
2. The complete packet exactly as emitted by the script
3. A request to return the worker JSON contract

Pass packet stdout byte-for-byte; do not retype, summarize, reformat, or re-serialize it. Do not deliberately send conversation history, architecture notes, expected conclusions, or repository tools. Treat the worker as read-only even when the task asks for a code change.

4. Validate the response

Reject malformed output and claims whose cited file/range is absent from the packet. Treat uncertain graph edges as hypotheses, not established calls.

For each proposed edit:

1. Confirm its file and original range are present in the packet.
2. Re-read the current affected unit and relevant tests/callers as coordinator.
3. Apply it only when the user's request authorizes source changes.
4. Run proportionate tests and checks; never trust the worker's claimed result.

5. Permit one focused expansion

If the worker returns status: needs_context, inspect missing_context and build one replacement packet that adds only the requested symbol, relationship, or line range to the original anchors, under one aggregate budget. Re-send the full task with that single packet to a fresh worker; do not stack packets across messages or let the worker browse. If the second response still lacks context, stop delegating and handle or escalate the task in the coordinator.

Error Handling

• symbol_not_found: re-check the name against the repository or query Trailmark for the exact node ID.
• ambiguous_symbol: use one returned exact node ID.
• invalid_depth: neighborhood mode is exactly one hop; use upstream or downstream for deeper traversal.
• anchor_exceeds_budget: switch to a meaningful --line-range or raise the explicit budget.
• path_not_found or entrypoint_path_not_found: increase depth only with a clear reason; otherwise report the static-analysis gap.
• no_source, stale_source, or path_outside_root: do not delegate the affected slice.
• unsupported_trailmark: install or select Trailmark 0.5.x; do not silently use a different schema.
• trailmark_analysis_failed: correct the reported language/parser failure before delegating.
• io_error: a filesystem failure (permissions, symlink loop); fix the target tree and retry.

Example Requests

• "Have a small local model explain Auth.verify and list its assumptions."
• "Give a worker only the entrypoint path into execute_query and classify validation gaps."
• "Ask a weak model to propose a replacement for lines 80-105, then verify its edit yourself."

Input to Output Example

Input: "Have a small worker explain Auth.verify and list its assumptions."

Coordinator: resolve the exact Auth.verify node, generate an 8K-or-smaller neighborhood packet at depth 1, and pass the task plus packet verbatim.

Accepted worker output:

{
  "status": "complete",
  "answer": "Verifies the token signature before dispatch.",
  "evidence": [
    {"claim": "Signature verification gates dispatch", "file": "auth.py", "start_line": 42, "end_line": 48}
  ],
  "proposed_edits": [],
  "missing_context": [],
  "uncertainties": ["The cryptographic backend is an unresolved external node"]
}