precision-mastery

Resources

scripts/
  validate-precision-usage.sh
references/
  tool-reference.md

Precision Mastery

The precision engine provides token-efficient alternatives to native tools (Read, Edit, Write, Grep, Glob, WebFetch). When used correctly, you save 75-95% of tokens on file operations. This skill teaches optimal usage.

Verbosity Cheat Sheet

Use the lowest verbosity that meets your needs. Verbosity directly impacts token consumption.

Operation	Default	Recommended	Why
precision_write	standard	count_only	You provided the content; just confirm success
precision_edit	with_diff	minimal	Confirm applied; skip diffs unless debugging
precision_read	standard	standard	You need the content
precision_grep (discovery)	standard	files_only via output.format	Discovery phase, not content phase
precision_grep (content)	standard	matches via output.format	Need actual matched lines
precision_glob	standard	paths_only via output.format	You need file paths, not stats
precision_exec (verify)	standard	minimal	Unless you need full stdout/stderr
precision_exec (debug)	standard	standard	Need output to diagnose
precision_fetch	standard	standard	You need the content
discover	files_only (verbosity param)	files_only	Discovery phase, not content phase
precision_symbols	locations (verbosity param)	locations	File:line is usually enough

Token Multipliers:

• count_only: ~0.05x tokens
• minimal: ~0.2x tokens
• standard: ~0.6x tokens
• verbose: 1.0x tokens

Golden Rule: Use count_only for writes/edits where you don't need to read back what you just wrote.

Extract Mode Selection (precision_read)

Before reading a file, decide what you need from it. Extract modes reduce tokens by 60-95% compared to full content.

Mode	When to Use	Token Savings	Example Use Case
content	Need full file to read/understand	0%	Reading config files, reading code to edit
outline	Need structure without content	60-80%	Understanding file organization, finding functions
symbols	Need exported symbols for imports	70-90%	Building import statements, API surface analysis
ast	Need structural patterns	50-70%	Refactoring, pattern detection
lines	Need specific line ranges	80-95%	Reading specific functions after grep

Best Practices:

1. Start with outline to understand file structure
2. Use symbols when building imports or understanding API surface
3. Use lines with range: { start, end } after grep finds a location
4. Only use content when you actually need the full file

# Step 1: Get structure
precision_read:
  files: [{ path: "src/components/Button.tsx", extract: outline }]
  verbosity: standard

# Step 2: If you need full content, read it
precision_read:
  files: [{ path: "src/components/Button.tsx", extract: content }]
  verbosity: standard

Batching Patterns

Batching is the single most important token saving technique. Always batch operations when possible.

1. Multi-File Read (Single Call)

Read 5-10 files in one precision_read call instead of 5-10 separate calls.

# Bad (5 separate calls)
precision_read:
  files: [{ path: "file1.ts" }]
precision_read:
  files: [{ path: "file2.ts" }]
# ...

# Good (1 batched call)
precision_read:
  files: [
    { path: "file1.ts", extract: outline },
    { path: "file2.ts", extract: outline },
    { path: "file3.ts", extract: outline },
    { path: "file4.ts", extract: outline },
    { path: "file5.ts", extract: outline }
  ]
  verbosity: minimal

2. Multi-Query Discover (Single Call)

Run grep + glob + symbols queries simultaneously in one discover call. This is the most powerful discovery pattern.

discover:
  queries:
    - id: find_components
      type: glob
      patterns: ["src/components/**/*.tsx"]
    - id: find_api_routes
      type: glob
      patterns: ["src/api/**/*.ts", "src/app/api/**/*.ts"]
    - id: find_auth_usage
      type: grep
      pattern: "useAuth|getSession|withAuth"
      glob: "src/**/*.{ts,tsx}"
    - id: find_hooks
      type: symbols
      query: "use"
      kinds: ["function"]
  verbosity: files_only

Why this matters: Parallel execution means all 4 queries finish in ~50ms instead of ~200ms sequential.

3. Multi-Edit Atomic Transaction (Single Call)

Apply multiple edits across files in one precision_edit call with atomic transaction. If any edit fails, all roll back.

precision_edit:
  edits:
    - path: "src/components/Button.tsx"
      find: "export default Button"
      replace: "export { Button as default }"
    - path: "src/components/index.ts"
      find: "export { default as Button } from './Button'"
      replace: "export { Button } from './Button'"
  transaction:
    mode: "atomic"
  verbosity: minimal

4. Multi-File Write (Single Call)

Create multiple files in one precision_write call.

precision_write:
  files:
    - path: "src/features/user/index.ts"
      content: |
        export * from './types';
        export * from './api';
        export * from './hooks';
    - path: "src/features/user/types.ts"
      content: |
        export interface User {
          id: string;
          email: string;
          name: string;
        }
    - path: "src/features/user/api.ts"
      content: |
        import type { User } from './types';
        export const getUser = async (id: string): Promise<User> => { /* ... */ };
  verbosity: count_only

5. Batching Precision Tools (Optimal)

The highest form of batching: wrap multiple precision calls in a single transaction.

Each operation type (read, write, exec, query) uses the corresponding precision_engine tool's schema. For example:

• read operations use precision_read schema (with files array)
• write operations use precision_write schema (with files array)
• exec operations use precision_exec schema (with commands array)
• query operations use precision_grep/precision_glob schemas

batch:
  operations:
    read:
      - files:
          - path: "src/types.ts"
            extract: symbols
    write:
      - files:
          - path: "src/features/auth/types.ts"
            content: |
              export interface User {
                id: string;
                email: string;
                name: string;
              }
    exec:
      - commands:
          - cmd: "npm run typecheck"
            expect:
              exit_code: 0
  config:
    transaction:
      mode: atomic
  verbosity: minimal

Token Budget & Pagination

For large files or batch reads, use token_budget to control output size.

# Read up to 20 files, but cap total output at 5K tokens
precision_read:
  files: [
    { path: "file1.ts" },
    { path: "file2.ts" },
    # ...
  ]
  token_budget: 5000
  page: 1  # Start with page 1
  verbosity: standard

If results are truncated, increment page to get the next batch.

Output Format Selection (precision_grep)

precision_grep has multiple output formats: count_only, files_only, locations, matches, context.

Format	Use Case	Token Cost
count_only	Gauge scope	Very Low
files_only	Discovery phase	Low
locations	Find where something exists	Medium
matches	Need actual matched lines	High
context	Need surrounding code	Very High

Progressive Disclosure: Start with count_only to gauge scope, then files_only to build a target list, then matches to get content.

Discover Tool Orchestration

The discover tool is a meta-tool that runs multiple queries (grep, glob, symbols) in parallel. Always use it BEFORE implementation.

Discovery Pattern:

1. Run discover with multiple queries
2. Analyze results to understand scope
3. Plan work based on discovery findings
4. Execute with batching

# Step 1: Discover
discover:
  queries:
    - id: existing_files
      type: glob
      patterns: ["src/features/auth/**/*.ts"]
    - id: existing_patterns
      type: grep
      pattern: "export (function|const|class)"
      glob: "src/features/**/*.ts"
  verbosity: files_only

# Step 2: Read key files with outline based on discovery
precision_read:
  files: [{ path: "src/features/auth/index.ts", extract: outline }]
  verbosity: minimal

# Step 3: Execute based on what was discovered
precision_write:
  files:
    - path: "src/features/auth/middleware.ts"
      content: "..."
  verbosity: count_only

precision_exec Patterns

1. Background Processes

Run long-running processes in the background to avoid blocking.

precision_exec:
  commands:
    - cmd: "npm run dev"
      background: true
  verbosity: minimal

2. Retry Patterns

Automatically retry flaky commands.

precision_exec:
  commands:
    - cmd: "npm install"
      retry:
        max: 3
        delay_ms: 1000
  verbosity: minimal

3. Until Patterns

Poll until a condition is met.

precision_exec:
  commands:
    - cmd: "curl http://localhost:3000/api/health"
      until:
        pattern: "ok"
        timeout_ms: 30000
  verbosity: minimal

precision_fetch Patterns

1. Batched URLs

Fetch multiple URLs in one call.

precision_fetch:
  urls:
    - url: "https://api.example.com/users"
    - url: "https://api.example.com/posts"
    - url: "https://api.example.com/comments"
  verbosity: standard

2. Extract Modes

Extract specific data from JSON responses.

precision_fetch:
  urls:
    - url: "https://api.example.com/users"
      extract: json  # Extract mode: raw, text, json, markdown, structured, etc.
  verbosity: standard

3. Service Registry Auth

Use pre-configured services for automatic authentication.

precision_fetch:
  urls:
    - url: "https://api.openai.com/v1/models"
      service: "OpenAI"  # Auto-applies bearer token from config
  verbosity: standard

Anti-Patterns (NEVER DO THESE)

1. Using native tools: Read, Edit, Write, Glob, Grep, WebFetch should be avoided. Use precision equivalents.

2. Setting verbosity to "verbose" for writes/edits: Wastes tokens. You just wrote the content, why read it back?

3. Reading entire files when you only need outline/symbols: Use extract modes.

4. Running discover queries one at a time: Batch them.

5. Using precision_read when precision_grep would find it faster: Grep is optimized for search.

6. Reading a file you just wrote: You already know the content.

7. Not using discover before implementation: Blind implementation leads to mismatched patterns.

8. Making multiple sequential precision tool calls that could be batched: If 3+ calls to the same tool, batch them.

9. Using verbosity: verbose as default: Only use it when debugging.

10. Ignoring token_budget for large batch reads: Without a budget, you might get truncated results.

Escalation Procedure

If a precision tool fails:

1. Check the error: Is it user error (wrong path, bad syntax)? Fix and retry.

2. If tool genuinely fails: Use native tool for THAT SPECIFIC TASK only.

3. Return to precision tools: For the next operation.

4. Log the failure: To .goodvibes/memory/failures.json.

Example:

• precision_read fails on a specific file => Use Read for that file only, return to precision_read for other files.
• precision_edit fails on a specific edit => Use Edit for that edit only, return to precision_edit for other edits.

NEVER: Abandon precision tools entirely because one call failed.

Decision Tree: Which Tool?

Do I know the exact file paths?
  |-- Yes -- precision_read (with appropriate extract mode)
  +-- No -- Do I know a pattern?
      |-- Yes -- precision_glob
      +-- No -- Am I searching for content?
         |-- Yes -- precision_grep
         +-- No -- Am I searching for symbols?
            |-- Yes -- precision_symbols
            +-- No -- Use discover with multiple query types

Special-purpose tools (not in tree above):

• precision_notebook — Jupyter notebook cell operations (replace/insert/delete with cell_id targeting)
• precision_agent — Spawn headless Claude sessions with dossier-based context injection
• precision_config — Runtime configuration (get/set/reload)

Performance Benchmarks

Token Savings:

• outline vs content: 60-80% savings
• symbols vs content: 70-90% savings
• count_only vs verbose: 95% savings
• Batched 5 files vs 5 separate calls: 40-60% savings (overhead reduction)
• Parallel discover 4x vs sequential: 75% speedup, similar token cost

Time Savings:

• Parallel discover (4 queries): ~50ms vs ~200ms sequential
• Batched writes (5 files): ~80ms vs ~400ms separate
• Batched edits with transaction: atomic rollback on failure

Quick Reference

Most common patterns:

# 1. Discover before implementing
discover:
  queries:
    - id: files
      type: glob
      patterns: ["pattern"]
    - id: patterns
      type: grep
      pattern: "regex"
  verbosity: files_only

# 2. Read with outline first
precision_read:
  files: [{ path: "file.ts", extract: outline }]
  verbosity: minimal

# 3. Batch writes with count_only
precision_write:
  files:
    - { path: "file1.ts", content: "..." }
    - { path: "file2.ts", content: "..." }
  verbosity: count_only

# 4. Batch edits with atomic transaction
precision_edit:
  edits:
    - { path: "f1.ts", find: "...", replace: "..." }
    - { path: "f2.ts", find: "...", replace: "..." }
  transaction: { mode: "atomic" }
  verbosity: minimal

# 5. Verify with minimal output
precision_exec:
  commands:
    - { cmd: "npm run typecheck", expect: { exit_code: 0 } }
  verbosity: minimal

---

Remember: The precision engine saves tokens, but only when you choose the right verbosity, extract modes, and batching patterns. Use this skill as a cheat sheet for efficient tool usage.