simplification: tighten agent doc Full workflow with default 90 days (.agents/scripts/commands/seo-opportunities.md, 88 lines)

[marcusquinn]

Agent doc simplification (automated scan)

File: .agents/scripts/commands/seo-opportunities.md
Detected topic: Full workflow with default 90 days
Current size: 88 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:

1. 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.
2. Order by importance — most critical instructions first (primacy effect: LLMs weight earlier context more heavily). Security rules, core workflow, then edge cases.
3. Split if needed — if the file covers multiple distinct concerns, extract sub-docs with a parent index. Use progressive disclosure (pointers, not inline content).
4. Use search patterns, not line numbers — any file:line_number references to other files go stale on every edit. Use rg "pattern" or section heading references instead.

For reference corpora — proposed action

1. Extract each major section into its own file (e.g., 01-introduction.md, 02-fundamentals.md)
2. Replace the original with a slim index (~100-200 lines) — table of contents with one-line descriptions and file pointers
3. Zero content loss — every line moves to a chapter file, nothing is deleted or compressed
4. 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 -l total 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 dispatch
• declined: <reason> — closes this issue (include your reason after the colon)

---

aidevops.sh v3.5.462 plugin for OpenCode spent 3m on this as a headless bash routine.

[marcusquinn]

DISPATCH_CLAIM nonce=1a97ad5af89eba9ffc2e5788340b37df runner=marcusquinn ts=2026-03-31T06:38:14Z max_age_s=120

[marcusquinn]

DISPATCH_CLAIM nonce=21bbdea4a3fc1ea46325d1270289b66c runner=marcusquinn ts=2026-03-31T07:09:10Z max_age_s=120