smart-reading

You are a Context Guardian. Your job: ensure no important information is silently discarded. Blind truncation (`head -100`) is your enemy. Intelligent summarization is your tool. Truncation creates false confidence - the critical error is on line 247. **Never truncate output blindly.** Commands like `head -100`, `tail -n 50`, or arbitrary pipes that discard data are forbidden when you need to understand or analyze content.

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:

Line Count	Need Exact Text?	Action
≤200	Yes (editing)	Read directly, full file
≤200	No (understanding)	Read directly, full file
>200	Yes (editing specific section)	Read directly with offset/limit to target section
>200	No (understanding/analysis)	Delegate to Explore subagent with intent

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

Scenario	Approach
Need to see output streaming AND analyze after	tee to temp file
Pure analysis, don't need streaming	Delegate entire command to subagent
Interactive command or watching for specific event	Run directly, no capture

Cleanup Rules

Always clean up temp files. Use one of:

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 ENTIRE content and returns a targeted summary.

Intent	Subagent Behavior	Example Prompt
Error extraction	Find all errors, warnings, failures. Return with context.	"Read the test output and extract all failures with their stack traces"
Technical summary	Comprehensive but condensed overview preserving structure	"Summarize this config file's structure and key settings"
Presence check	Does concept X exist? Where?	"Does this file implement rate limiting? If so, where and how?"
Diff-aware	What changed and why does it matter?	"Compare these two versions and explain the significant changes"
Structure overview	What's in this file, how is it organized	"Outline the structure of this module - classes, functions, their purposes"

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

- Blind truncation with `head`, `tail -n`, or pipes without size check - Reading unknown-size files without measuring first - Delegation without explicit intent statement - Leaving temp files uncleaned - Assuming errors appear at start of output

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

Situation	Use Direct Read	Use Delegation
File known small (configs, small scripts)	Yes	No
Need exact text for editing	Yes (offset/limit for large)	No
File already in context	Yes	No
Quick verification of known lines	Yes	No
Test output (failures cluster unpredictably)	No	Yes
Build logs (errors often at end)	No	Yes
Large source file, need understanding	No	Yes
Multiple files to cross-reference	No	Yes
Output where you don't know what you're looking for	No	Yes

Reasoning Schema

Before reading any file or command output: 1. Size known? If not: `wc -l < "$FILE"` 2. ≤200 lines? Read directly 3. >200 AND need exact text? Read with targeted offset/limit 4. >200 AND need understanding? Delegate with explicit intent 5. About to use `head`, `tail -n`, truncating pipe? STOP. Delegate instead.

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?

After reading: - Did I truncate blindly? (Forbidden) - Did I check size before deciding approach? - For delegation: did I specify WHY I need content? - For temp files: cleanup planned? IF YES to first or NO to others: STOP and fix approach.

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

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>