Always-on 'Read fully, then be lazy' rule wedges agents mid-read on large markdown files #745

Summary

With ponytail active at the default full level, agents that need to work with a large Markdown file (thousands of lines, e.g. generated docs, long changelogs, big READMEs) start a full read of the file and stall mid-read. The session appears frozen and stays that way: every follow-up prompt re-injects the same always-on instruction, so the agent keeps trying to ingest the whole file and never recovers. Reported from a real install: "after installing it, the AI agent could no longer read large .md files with many lines; it froze in the middle of reading them."

Load-bearing rule (main branch, skills/ponytail/SKILL.md)

"Never lazy about understanding the problem. The ladder shortens the solution, never the reading. Trace the whole thing first — every file the change touches, the actual flow — before picking a rung. Laziness that skips comprehension to ship a small diff is the dangerous kind: it dresses up as efficiency and ships a confident wrong fix. Read fully, then be lazy."

This is injected on every session start (SessionStart) and into every subagent (SubagentStart), so the "read everything the task touches, in full, before acting" pressure is always on.

Why it wedges

1. The rule tells the agent to read the whole file before any action. For a large .md, "read fully" means ingesting hundreds of KB into context.
2. The full read overwhelms the context budget mid tool call; the agent stalls or errors partway, which the user experiences as a freeze "in the middle of reading".
3. Because the rule is re-injected on every new prompt, retrying does not help. The session stays wedged until the plugin is disabled.

Mode levels do not mitigate

filterSkillBodyForMode (hooks/ponytail-instructions.js) only filters the intensity table rows and the lite/full/ultra example bullets. The "When NOT to be lazy" paragraph above is a plain rule, so it is kept verbatim at lite, full, and ultra. /ponytail lite does not remove the blocking instruction (consistent with #664: the levels are 96 of 99 lines identical).

Also affects instruction-only adapters

Hosts that auto-load AGENTS.md from a project (opencode, jcode, Amp, Qoder, Swival, Jules, Copilot CLI) get this rule always-on even without the hooks, and most of them have no partial-read discipline for big docs either.

Suggested fixes

1. Scope the rule to code. Change it so "read fully / trace the whole thing" applies to the source files the change touches, with an explicit carve-out for documents and data files: for large files (e.g. > ~500 lines), read structure first — headings, TOC, first and last N lines — and only read fully on explicit request.
2. Make lite actually lighter. Have filterSkillBodyForMode drop this paragraph for lite (and/or add a file-size threshold below which "read fully" applies).
3. Name the cost. One sentence acknowledging the context budget: "if a full read would exceed the remaining context, read structurally and say what you skipped."

Repro

1. Install the Claude Code plugin per the README (or put the checkout's AGENTS.md in any project).
2. Open a project containing a large .md (10k+ lines).
3. Ask the agent to do anything involving that file: summarize it, extract a section, edit one heading.
4. Observe: agent starts a full read, stalls mid-file, and subsequent prompts stay stuck in the same state.

Expected behavior

For large documents the agent reads headings and the relevant sections, completes the task, and only does a full read when explicitly asked.