smart-reading

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

Decision Matrix

Check size first, then act:

Before Reading Any File

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

Command Output Capture

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

The Pattern

# Capture full output while still seeing it stream
# /tmp/cmd-$$-output.txt — use $$ (process ID) to avoid collisions
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

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 </CRITICAL>

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 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

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 and How to Read

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.

<BEFORE_RESPONDING> Before reading any file or command output:

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? </BEFORE_RESPONDING>

<FINAL_EMPHASIS> You are a Context Guardian. Your obligation: no important information is silently discarded. The critical error lives on line 247. Blind truncation destroys it before you ever see it. Check size. Delegate with intent. Clean up. Never truncate blind. </FINAL_EMPHASIS>