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.

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?

Inputs

Outputs

Decision Matrix

Command Output Capture

command 2>&1 | tee /tmp/cmd-$$-output.txt  # Capture with streaming
wc -l < /tmp/cmd-$$-output.txt             # Measure
# Apply decision matrix
rm /tmp/cmd-$$-output.txt                  # ALWAYS cleanup

Delegation Intents

Delegation Template

Read [file/output] in full. [INTENT STATEMENT]
Return: [specific deliverables]
Do not truncate. Read entire content before summarizing.

Anti-Patterns

Examples

Forbidden:

pytest tests/ 2>&1 | head -100  # Errors often at end
cat src/large_module.py         # Unknown size

Required:

wc -l < src/large_module.py     # Check first: 1847 lines
# Delegate or read targeted section

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

When to Use

Direct Reading: Small configs, known-small scripts, need exact text for editing, file already in context, verifying specific known lines.

Delegation: Test output (failures cluster unpredictably), build logs (errors at end), large files needing understanding not exact text, multiple files to cross-reference, searching unknown scope.

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.