#824 Skill guides lack progressive reveal boundaries — agents over-read by 4x

Problem

The swamp skill system uses a 3-tier progressive reveal design: SKILL.md routing table → guide files → deeper reference files. The design intends agents to read the routing table, load only the top section of matching guides (Quick Reference + rules), and consult deeper sections on demand.

In benchmarking, agents consistently ignore this and front-load entire guides before running a single command. After the routing table loads (92 lines), the agent reads the full model guide (575 lines) and full workflow guide (688 lines) — 1,265 lines consumed upfront. One run read ~2,700 lines total. The intended reading path for the same task is ~340–500 lines.

This over-reading inflates input token cost on every subsequent turn because the documentation stays in context for the entire conversation. It accounts for a significant portion of swamp's token overhead vs competitors.

Root Causes

1. Rule #3 in SKILL.md enables multi-guide front-loading

Current Rule #3 (.claude/skills/swamp/SKILL.md lines 81-82):

3. **Load multiple guides when needed.** If the question spans topics (e.g.
   running a model in a workflow), load both relevant guides.

Agents pattern-match their task to the example and read both guides in full. The rule says "load" without defining what that means — agents interpret it as "read the entire file."

2. Guide files have no depth boundary

Each guide flows continuously from essential context to advanced reference material with no structural signal for where to stop reading. For example, the model guide:

• Lines 1–70: Essential (Output Modes, Direct Execution, Creation Rules, Quick Reference table)
• Lines 71–575: Detailed reference (repo structure, type search, create/edit, validate, run methods, advanced scenarios)

An agent doing a Read call gets all 575 lines with no marker indicating "stop here for most tasks."

Required Changes

Change A: Rewrite Rule #3 in SKILL.md

File: .claude/skills/swamp/SKILL.md lines 81-82

Replace:

3. **Load multiple guides when needed.** If the question spans topics (e.g.
   running a model in a workflow), load both relevant guides.

With:

3. **Read guides selectively.** If the question spans topics, load the
   relevant guides but only read up to the **--- Detailed Reference** marker
   in each. Do NOT read past that marker upfront — treat everything below it
   as on-demand reference. Return to specific sections only when you hit a
   concrete need the Quick Reference doesn't answer.

Change B: Add boundary markers to all 10 guide files

Insert a consistent boundary marker in each guide at the point where essential content ends. Use this exact format for the marker:

---

> **Detailed Reference** — the sections below cover specific tasks in depth.
> The Quick Reference above is sufficient for most operations. Read sections
> below on demand when you hit a specific need.

Insert the marker at these locations (insert AFTER the listed line):

Guide file	Insert after line	Last essential section above marker
references/model/guide.md (575 lines)	Line 70	Quick Reference table ends
references/workflow/guide.md (688 lines)	Line 91	"Always Get Schema First" section ends
references/data/guide.md (327 lines)	Line 59	Quick Reference table + concepts link
references/extension/guide.md (459 lines)	Line 59	Quick Reference table ends
references/repo/guide.md (387 lines)	Line 25	Quick Reference table ends
references/vault/guide.md (375 lines)	Line 39	Quick Reference table ends
references/report/guide.md (172 lines)	Line 26	Quick Reference table ends
references/issue/guide.md (262 lines)	Line 67	Commands table + basic examples end
references/extension-publish/guide.md (300 lines)	Line 15	Intro + state machine diagram
references/troubleshooting/guide.md (112 lines)	Line 22	Diagnostic mindset principles

Important notes on specific guides:

• workflow/guide.md: The boundary is at line 91, NOT line 54. The "IMPORTANT: Always Get Schema First" section (lines 71-91) is essential — skipping it causes agents to write workflow YAML without fetching the schema, which is a top failure mode.
• extension-publish/guide.md: This guide is a state machine walkthrough, not a quick-reference format. The essential part is just the intro + state diagram (15 lines). State-by-state details are reference material.

Verification

After making changes:

1. Run deno fmt on all modified .md files
2. Confirm every guide has exactly one > **Detailed Reference** marker
3. Confirm SKILL.md Rule #3 references the marker text
4. The marker text must be identical across all guides so the rule works consistently

Expected Impact

Metric	Before	After
Model+workflow task reading	~1,265 lines	~160 lines
Reduction	—	~87%
Per-turn input token savings	—	~1,100 lines fewer in context

Context

This issue was identified through competitive benchmarking analysis documented in ~/Downloads/benchmarking/analysis/guide-overreading-problem.md. A related but separate issue (discovery loop problem) is documented in the same directory.