simplification: tighten agent doc Agent Browser - Headless Browser Automation CLI (.agents/tools/browser/agent-browser.md, 180 lines) #13979
Description
Agent doc simplification (automated scan)
File: .agents/tools/browser/agent-browser.md
Detected topic: Agent Browser - Headless Browser Automation CLI
Current size: 180 lines
Classify before acting
First, determine the file type — the correct action depends on whether this is an instruction doc or a reference corpus:
- Instruction doc (agent rules, workflows, decision trees, operational procedures): Tighten prose, reorder by importance, split if multiple concerns. Follow guidance below.
- Reference corpus (SKILL.md, domain knowledge base, textbook-style content with self-contained sections): Do NOT compress content. Instead, split into chapter files with a slim index. See
tools/code-review/code-simplifier.md"Reference corpora" classification (GH#6432).
For instruction docs — proposed action
Tighten and restructure this agent doc. Follow tools/build-agent/build-agent.md guidance. Key principles:
- Preserve all institutional knowledge — every verbose rule exists because something broke without it. Do not remove task IDs, incident references, error statistics, or decision rationale. Compress prose, not knowledge.
- Order by importance — most critical instructions first (primacy effect: LLMs weight earlier context more heavily). Security rules, core workflow, then edge cases.
- Split if needed — if the file covers multiple distinct concerns, extract sub-docs with a parent index. Use progressive disclosure (pointers, not inline content).
- Use search patterns, not line numbers — any
file:line_numberreferences to other files go stale on every edit. Userg "pattern"or section heading references instead.
For reference corpora — proposed action
- Extract each major section into its own file (e.g.,
01-introduction.md,02-fundamentals.md) - Replace the original with a slim index (~100-200 lines) — table of contents with one-line descriptions and file pointers
- Zero content loss — every line moves to a chapter file, nothing is deleted or compressed
- Reconcile existing chapter files — if partial splits already exist, deduplicate and keep the most complete version
Verification
- Content preservation: all code blocks, URLs, task ID references (
tNNN,GH#NNN), and command examples must be present before and after - No broken internal links or references
- Agent behaviour unchanged (test with a representative query if possible)
- For reference corpora:
wc -ltotal of chapter files >= original line count minus index overhead
Confidence: medium
Automated scan flagged this file for maintainer review. The best simplification strategy requires human judgment — some files are appropriately structured already. Reference corpora (SKILL.md, domain knowledge bases) need restructuring into chapters, not content reduction.
To approve or decline, comment on this issue:
approved— removes the review gate and queues for automated dispatchdeclined: <reason>— closes this issue (include your reason after the colon)
aidevops.sh v3.5.454 plugin for OpenCode spent 1m on this as a headless bash routine.