Smart Reading

Truncation creates false confidence: you think you "saw" the output, but the critical error was on line 247.

Smart Reading Protocol

A behavioral protocol for reading files and command output without losing critical context.

Invariant Principles

1. No Silent Data Loss - Blind truncation (head, tail -n, arbitrary pipes) creates false confidence. Critical errors often appear at end of output.
2. Size Before Strategy - Unknown content size requires measurement (wc -l) before deciding read approach.
3. Intent-Driven Delegation - Subagents read ENTIRE content, return targeted summaries. Specify WHY you need content.
4. Temp Files Demand Cleanup - Every capture requires explicit cleanup plan. Use $$ for collision-free naming.

The Problem

Claude often pipes output through head -100 to "save tokens." This causes:

• Silent data loss
• Missed errors (which often appear at the END)
• Wrong conclusions based on incomplete information
• Wasted debugging cycles

The Solution

Check size first. Then decide approach.

Unknown file/output → wc -l → decision → read directly OR delegate to subagent

Decision Matrix

Before Reading Any File

wc -l < "$FILE"  # Get line count first

Command Output Capture

For commands with unpredictable output size, capture to a temp file first using tee.

The Pattern

# Capture full output while still seeing it stream
command 2>&1 | tee /tmp/cmd-$$-output.txt

# Check size
wc -l < /tmp/cmd-$$-output.txt

# Apply decision matrix (read directly or delegate)
# ...

# ALWAYS cleanup
rm /tmp/cmd-$$-output.txt

Temp File Naming

Use $$ (process ID) to avoid collisions:

• /tmp/cmd-$$-output.txt - general command output
• /tmp/test-$$-output.txt - test runs
• /tmp/build-$$-output.txt - build logs

When to Capture vs Delegate Entirely

Cleanup Rules

1. Immediate cleanup after analysis:

   rm /tmp/cmd-$$-output.txt
   

2. Trap-based cleanup for complex flows:

   trap 'rm -f /tmp/cmd-$$-output.txt' EXIT
   

3. Delegate to subagent - subagent handles its own cleanup

Capture Examples

Test run with capture:

pytest tests/ 2>&1 | tee /tmp/test-$$-output.txt
wc -l < /tmp/test-$$-output.txt  # Check size
# If >200: delegate analysis of /tmp/test-$$-output.txt
# If ≤200: read directly
rm /tmp/test-$$-output.txt

Build with capture:

npm run build 2>&1 | tee /tmp/build-$$-output.txt
# Analyze...
rm /tmp/build-$$-output.txt

Pure delegation (no capture needed):

Task(Explore): Run `pytest tests/` and extract all failures with
stack traces. Return a summary of what failed and why.

Delegation Intents

When delegating to a subagent, specify WHY you need the file. The subagent reads the ENTIRE content and returns a targeted summary.

Delegation Template

Read [file/output] in full. [INTENT STATEMENT]

Return:
- [What you need back]
- [Any specific format requirements]

Do not truncate. Read the entire content before summarizing.

Anti-Patterns

Anti-Pattern Examples

Forbidden:

pytest tests/ 2>&1 | head -100  # WRONG: errors often at end
cat src/large_module.py         # WRONG: might be 2000 lines

Required:

wc -l < src/large_module.py  # Returns: 1847
# Now delegate to subagent for summary, or read specific section

Task(Explore): Run pytest tests/ and analyze the output. Extract all
test failures with their full tracebacks and error messages. Summarize
the failure patterns.

When Direct Reading is Correct

• Files known to be small (configs, small scripts)
• You need exact text for editing (use Read with offset/limit for large files)
• File is already in context from earlier in conversation
• Quick verification of specific lines you already know about

When Delegation is Correct

• Test output (failures cluster unpredictably)
• Build logs (errors often at end)
• Large source files when you need understanding, not exact text
• Multiple files to cross-reference
• Any output where you don't know what you're looking for

Reasoning Schema

Before running command with unpredictable output: 6. Capture with tee for post-analysis? Or delegate entire command? 7. If capturing: cleanup plan exists? 8. If delegating: intent specified clearly?

Self-Check

Before completing:

• Size checked before reading unknown content
• No blind truncation used
• Delegation includes explicit intent if used
• Temp files cleaned up if created
• Critical information not lost to truncation

If ANY unchecked: STOP and fix approach.

1. Do I know the size? If not, check with wc -l
2. Is it ≤200 lines? → Read directly
3. Is it >200 lines AND I need exact text? → Read with targeted offset/limit
4. Is it >200 lines AND I need understanding? → Delegate with explicit intent
5. Am I about to use head, tail -n, or a truncating pipe? → STOP. Delegate instead.

Before running a command with unpredictable output:

6. Should I capture with tee to analyze after? Or delegate the entire command?
7. If capturing: Did I plan for cleanup?
8. If delegating: Did I specify the analysis intent clearly?