Optimize builtin tool instructions for conciseness

[dgageot]

Apply Claude 4 prompt engineering best practices to all builtin tool instructions: remove meta-commentary and filler, eliminate redundancy with tool descriptions/schemas, use direct bullet points over verbose prose, and frontload critical behavioral guidance.

Affected tools: filesystem, shell, think, todo, fetch, memory, deferred, tasks, model_picker, user_prompt, skills, script_shell.

Update tests and e2e cassettes to match new instruction text.

Assisted-By: docker-agent

[docker-agent]

Review Summary

Assessment: 🟢 APPROVE

This PR successfully optimizes builtin tool instructions following Claude 4 prompt engineering best practices. The changes remove verbose prose, eliminate redundancy, and adopt concise bullet-point formatting while preserving all critical information.

Analysis

Scope: 22 files changed

• 12 tool instruction files (pkg/tools/builtin/*.go)
• 6 test cassettes (e2e/testdata/cassettes/*.yaml)
• 2 test files (pkg/session/session_test.go, pkg/tools/builtin/memory_test.go)
• 2 test files (pkg/tools/builtin/shell_test.go, pkg/tools/builtin/shell_instructions.go deleted)

Key Changes:

1. Filesystem tool: Reduced from 3 subsections to 4 bullet points
2. Memory tool: Condensed from detailed explanations to concise guidance
3. Shell tool: Inlined instructions (removed separate file), made more compact
4. Other tools: All instructions shortened while maintaining critical behavioral guidance

Quality Checks:

• ✅ All test assertions updated to match new instruction text
• ✅ Test cassettes updated with new instruction content
• ✅ No logic errors or missing critical information
• ✅ String formatting and escaping correct
• ✅ Go code syntactically sound

Verdict

No bugs found in the changed code. The refactoring maintains functional equivalence while improving conciseness and readability. All tests are properly updated to reflect the new instruction text.