docs: full content and information architecture analysis

[diberry]

Goal

Conduct a comprehensive analysis of the Squad docs site from a content lead and information architecture perspective. The docs have grown organically across many PRs — they need a structural review to ensure coherent navigation, progressive disclosure, and no gaps or redundancy.

Scope

Content audit

• Inventory all pages by section (Get Started, Guide, Features, Reference, Scenarios, Concepts, Cookbook)
• Flag: duplicate content across pages, orphaned pages, missing cross-links
• Assess: is each page in the right section? Are any misplaced?
• Check: does the reading order make sense for a new user vs. an experienced user?

Information architecture review

• Evaluate navigation structure: is the sidebar hierarchy logical?
• Identify: content gaps (features documented in squad.agent.md but missing from docs)
• Identify: content that exists but has no clear audience or purpose
• Assess progressive disclosure: can a new user get started without drowning in advanced content?

Recommendations

• Proposed restructuring (if needed): page moves, merges, splits
• New pages needed (with placement)
• Pages to deprecate or archive
• Navigation improvements
• Content style consistency check (Microsoft Style Guide compliance)

Deliverable

A single analysis document posted as a comment on this issue, with actionable recommendations ranked by impact.

Owner

PAO (DevRel) — content perspective
Flight (Lead) — architecture perspective

[github-actions]

🏗️ Squad Triage — Flight (Lead)

Issue: #62 — docs: full content and information architecture analysis
Assigned to: DSKY (TUI Engineer)
Reason: Issue relates to frontend/UI work

@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.

Team roster:

• Flight (Lead) → label: squad:flight
• Procedures (Prompt Engineer) → label: squad:procedures
• EECOM (Core Dev) → label: squad:eecom
• FIDO (Quality Owner) → label: squad:fido
• PAO (DevRel) → label: squad:pao
• CAPCOM (SDK Expert) → label: squad:capcom
• CONTROL (TypeScript Engineer) → label: squad:control
• Surgeon (Release Manager) → label: squad:surgeon
• Booster (CI/CD Engineer) → label: squad:booster
• GNC (Node.js Runtime) → label: squad:gnc
• Network (Distribution) → label: squad:network
• RETRO (Security) → label: squad:retro
• INCO (CLI UX & Visual Design) → label: squad:inco
• GUIDO (VS Code Extension) → label: squad:guido
• Telemetry (Aspire & Observability) → label: squad:telemetry
• VOX (REPL & Interactive Shell) → label: squad:vox
• DSKY (TUI Engineer) → label: squad:dsky
• Sims (E2E Test Engineer) → label: squad:sims
• Handbook (SDK Usability) → label: squad:handbook
• Ralph (Work Monitor) → label: squad:ralph
• @copilot (Coding Agent) → label: squad:copilot

To reassign, remove the current squad:* label and add the correct one.

[diberry]

Information Architecture Review — Squad Documentation

Reviewer: Flight (Lead)
Date: 2025-07-24
Scope: Navigation structure, feature coverage, section coherence, orphaned content
Parallel audit: PAO is conducting a content quality audit on the same docs set.

---

1. Navigation Overview

Section	Pages in Nav	Files on Disk	Orphaned Files
Get Started	5	6	1
Guide	8	11	3
Features	33	39	4
Reference	7	8	1
Scenarios	25	26	0
Concepts	6	6	0
Cookbook	1	1	0
Standalone	4	4	0
Root-level (no section)	—	6	6
TOTAL	89	107	15

15 orphaned files exist on disk but are not wired into navigation.ts. These are invisible to users navigating the sidebar.

---

2. Section-by-Section IA Assessment

Get Started (5 pages) — ✅ Good

Pages: Quick start → Installation → Choose your path → Your First Session → Migration Guide

Assessment: Strong onboarding funnel. Reading order is logical — fast-track first, then deeper setup, then migration for existing users. Size is appropriate.

Issue: choose-your-interface.md exists on disk but isn't in navigation. Likely superseded by choosing-your-path.md — should be deleted or merged.

---

Guide (8 pages) — ⚠️ Identity Crisis

Pages: Tips & Tricks → Sample Prompts → Personal Squad → Interactive Shell → Extensibility → Building Extensions → Contributing → Contributors

Assessment: This section mixes three distinct content types:

1. Usage guides (Tips, Sample Prompts, Shell) — belong here
2. Feature documentation (Personal Squad) — belongs in Features
3. Community/contribution (Contributing, Contributors) — belong in a Community section or as standalones

Misplaced pages:

• Personal Squad → Move to Features. It's a core platform feature documented in squad.agent.md (§ Personal Squad — Ambient Discovery), not a general guide topic.
• Contributing / Contributors → Move to standalone pages or create a Community section alongside the existing community.md standalone page.

Orphaned files (3):

• guide/build-autonomous-agent.md — not in nav
• guide/faq.md — not in nav (high value, should be wired in)
• guide/github-auth-setup.md — not in nav (prerequisite content, should be in Get Started or Guide)

---

Features (33 pages) — 🔴 Bloated, Needs Sub-Grouping

Assessment: 33 pages in a flat list is the single biggest IA problem. Users scanning the sidebar see an undifferentiated wall of feature names. No mental model is provided for which features are core vs. advanced vs. infrastructure.

Recommended sub-grouping:

Sub-Group	Pages	Description
Core	Team Setup, Routing, Model Selection, Response Modes, Memory, Skills, Directives	Fundamentals every user needs
Workflow	Ceremonies, Reviewer Protocol, GitHub Issues, GitLab Issues, Labels & Triage, PRD Mode, Project Boards	How work flows through the team
Team Members	Ralph, @copilot Coding Agent, Human Team Members, Consult Mode	Different member types
Execution	Parallel Execution, Git Worktrees, Streams, Capability Routing	How agents run
Extensibility	Plugins, Marketplace, MCP, Upstream Inheritance, Export & Import	Extension points
Platform	VS Code, Remote Control, Enterprise Platforms, Distributed Mesh, Squad RC, Notifications	Where Squad runs
Infrastructure	Rate Limiting, KEDA Autoscaling	Scaling & ops

Orphaned files (4):

• features/built-in-roles.md — not in nav
• features/context-hygiene.md — not in nav (important best practice, should be wired)
• features/cost-tracking.md — not in nav (users care about costs)
• features/issue-templates.md — not in nav

---

Reference (7 pages) — ✅ Good

Pages: CLI → SDK → SDK API Reference → SDK Integration → Tools & Hooks → Config → Glossary

Assessment: Clean, well-scoped. SDK pages form a logical progression (overview → API → integration).

Potential issue: Nav slug reference/api may not match filename api-reference.md — verify Astro slug resolution or frontmatter override to avoid a 404.

Orphaned files (1):

• reference/vscode-troubleshooting.md — not in nav. Should be linked from the VS Code feature page or added to Reference.

---

Scenarios (25 pages) — ⚠️ Too Large, Mixed Content Types

Assessment: 25 pages make this the second-largest section. It mixes genuinely scenario-based content ("Solo Developer," "Monorepo," "Open Source") with operational/troubleshooting content that doesn't fit the "scenario" framing.

Misplaced pages:

• Troubleshooting → Should be standalone or in a dedicated Support section, not buried as scenario chore(scribe): Mandate ### YYYY-MM-DD: format in Scribe charter #24 of 25.
• Disaster Recovery → Operational concern, not a "scenario."
• Client Compatibility → Reference material (compatibility matrix), not a scenario.
• Release Process → Process documentation, better in Guide or Reference.
• Switching Models → Feature-adjacent, could be in Features or Guide.

Reading order: Generally logical — starts with project type (existing/new/solo), moves through complexity, ends with operations. But the sheer length means users won't discover pages past the first screen of items.

---

Concepts (6 pages) — ✅ Good

Pages: Architecture → Your Team → Memory & Knowledge → Parallel Work → GitHub Workflow → Portability

Assessment: Right size, right scope. These provide the mental model before diving into features. Good complement to Get Started.

Suggestion: Consider moving this section ABOVE Features in the nav to establish concepts before feature details.

---

Cookbook (1 page) — 🔴 Starved

Pages: Recipes (1)

Assessment: A single page doesn't justify its own nav section. Either:

1. Merge into Guide (as "Recipes" page)
2. Plan to populate with 3-5 recipes before GA
3. Remove the section until there's enough content

---

Standalone Pages (4) — ✅ Appropriate

Pages: What's New, SDK-First Mode, Community, Insider Program

Assessment: These are correctly standalone — they don't fit in any section hierarchy.

---

3. Orphaned Content Inventory

These 15 files exist in docs/src/content/docs/ but are NOT in navigation.ts:

File	Location	Recommendation
choose-your-interface.md	get-started/	Delete or merge into choosing-your-path.md
build-autonomous-agent.md	guide/	Wire into Guide nav (high-value content)
faq.md	guide/	Wire into Guide nav or make standalone
github-auth-setup.md	guide/	Wire into Get Started (prerequisite)
built-in-roles.md	features/	Wire into Features nav
context-hygiene.md	features/	Wire into Features nav (best practices)
cost-tracking.md	features/	Wire into Features nav (users care about this)
issue-templates.md	features/	Wire into Features nav
vscode-troubleshooting.md	reference/	Wire into Reference or link from VS Code feature page
sample-prompts.md	root	Delete — duplicate of guide/sample-prompts.md
tips-and-tricks.md	root	Delete — duplicate of guide/tips-and-tricks.md
tour-first-session.md	root	Delete or merge into get-started/first-session.md
tour-github-issues.md	root	Delete or merge into features/github-issues.md
tour-gitlab-issues.md	root	Delete or merge into features/gitlab-issues.md
guide.md	root	Delete — likely a leftover index page

---

4. Feature Coverage Matrix

Mapping every major feature in squad.agent.md to its documentation page. "COVERED" = dedicated page exists. "PARTIAL" = covered within another page. "MISSING" = no documentation.

squad.agent.md Feature	Docs Page	Status
Init Mode (Phase 1 & 2)	get-started/five-minute-start, first-session	✅ COVERED
Team Mode	features/team-setup	✅ COVERED
Personal Squad (Ambient Discovery)	guide/personal-squad	✅ COVERED
Issue Awareness	features/github-issues, gitlab-issues	✅ COVERED
Acknowledge Immediately ("Feels Heard")	—	❌ MISSING
Role Emoji in Task Descriptions	—	⚪ SKIP (internal behavior)
Directive Capture	features/directives	✅ COVERED
Routing	features/routing	✅ COVERED
Consult Mode	features/consult-mode	✅ COVERED
Skill Confidence Lifecycle	features/skills	🟡 PARTIAL (within Skills)
Response Mode Selection	features/response-modes	✅ COVERED
Per-Agent Model Selection	features/model-selection	✅ COVERED
Client Compatibility	scenarios/client-compatibility	✅ COVERED
MCP Integration	features/mcp	✅ COVERED
Eager Execution / Parallel Fan-Out	features/parallel-execution	✅ COVERED
Background Mode Selection	features/parallel-execution	🟡 PARTIAL
Shared File Architecture (Drop-Box)	—	❌ MISSING
Worktree Awareness & Lifecycle	features/worktrees	✅ COVERED
Orchestration Logging	—	❌ MISSING
Agent Spawning Mechanics	—	❌ MISSING
Ceremonies	features/ceremonies	✅ COVERED
Adding/Removing Team Members	features/team-setup	🟡 PARTIAL
Plugin Marketplace	features/marketplace, features/plugins	✅ COVERED
Source of Truth Hierarchy	—	❌ MISSING
Casting & Persistent Naming	—	❌ MISSING
Universe Allowlist / Overflow	—	❌ MISSING
Constraints (Coordinator Rules)	—	❌ MISSING
Reviewer Rejection Protocol	features/reviewer-protocol	✅ COVERED
Multi-Agent Artifact Format	—	❌ MISSING
Constraint Budget Tracking	—	❌ MISSING
GitHub Issues Mode	features/github-issues	✅ COVERED
Ralph — Work Monitor	features/ralph	✅ COVERED
Watch Mode (squad watch)	features/ralph	🟡 PARTIAL
PRD Mode	features/prd-mode	✅ COVERED
Human Team Members	features/human-team-members	✅ COVERED
Copilot Coding Agent	features/copilot-coding-agent	✅ COVERED
Routing Enforcement	—	⚪ SKIP (internal)

Summary: 20 COVERED, 5 PARTIAL, 9 MISSING, 2 SKIP (internal-only)

Key gaps:

• Casting & Persistent Naming — Users see agent names but don't understand why. This is a signature Squad feature with no docs page.
• Source of Truth Hierarchy — Critical for users customizing Squad. Which files matter? What takes precedence?
• Shared File Architecture (Drop-Box) — Explains how parallel work avoids conflicts. Users running into merge issues need this.
• Orchestration Logging — Users need to know where to find what happened.
• Agent Spawning Mechanics — Advanced users and contributors need this.

---

5. Navigation Order Recommendations

Current order issues:

1. Concepts appears AFTER Features and Scenarios — Users should understand concepts before diving into 33 features. Move Concepts up.
2. Cookbook is dead last — With only 1 page, it's a wasted nav slot. Merge or defer.
3. Features is a flat wall — 33 items with no grouping. Sub-sections needed.

Proposed nav order:

1. Get Started (5)        — Unchanged, good as-is
2. Concepts (6)           — MOVED UP from position 6
3. Guide (5-6)            — Slimmed: remove misplaced pages
4. Features               — Sub-grouped (see section 2 above)
   ├── Core (7)
   ├── Workflow (7)
   ├── Team Members (4)
   ├── Execution (4)
   ├── Extensibility (5)
   ├── Platform (6)
   └── Infrastructure (2)
5. Scenarios (20-22)      — Slimmed: move operational pages out
6. Reference (7-8)        — Add vscode-troubleshooting
7. Community (new)         — Contributing, Contributors, community.md

Learning path this creates:

Get Started (set up) → Concepts (understand the model) → Guide (practical tips) → Features (deep dives) → Scenarios (apply to your situation) → Reference (look things up)

---

6. Proposed Restructuring Summary

Immediate actions (low effort, high impact):

1. Wire 5 high-value orphaned pages into navigation: faq.md, context-hygiene.md, cost-tracking.md, github-auth-setup.md, build-autonomous-agent.md
2. Delete 5 root-level duplicates/leftovers: sample-prompts.md, tips-and-tricks.md, tour-*.md, guide.md
3. Move Concepts above Features in nav order
4. Move Personal Squad from Guide → Features

Medium-term actions (requires new content):

5. Create "Casting & Naming" feature page — document the persistent naming system
6. Create "Source of Truth" reference page — document the file hierarchy
7. Sub-group the Features section — 7 sub-groups as proposed above
8. Create Community section — pull Contributing, Contributors, community.md together
9. Merge or populate Cookbook — either add 3+ recipes or fold into Guide

Verify:

10. Check reference/api slug — file is api-reference.md but nav slug is reference/api. Confirm frontmatter override exists or fix the mismatch.

---

This review covers information architecture only. PAO's parallel content audit will assess page quality, accuracy, and completeness. Together these form the full docs analysis for the v1.0 documentation push.

[diberry]

Docs content audit — PAO (DevRel)

Issue: #62 | Author: PAO | Scope: Content quality, gaps, redundancy, style
Companion: Flight is handling IA/navigation in parallel

---

1. Page inventory

Total pages: 83 (72 in navigation + 11 orphaned/standalone)

Get Started (5 pages in nav, 1 orphan)

Page	Lines	Audience	Length	Notes
Quick start	87	New user	✅ Right-sized	Clean, scannable, good progressive disclosure
Installation	197	New user	⚠️ Long for install	Covers CLI, VS Code, SDK, personal squad, troubleshooting — could split
Choose your path	82	New user	✅ Good	Clear decision matrix
Your first session	303	New user	⚠️ Long	Excellent walkthrough but 303 lines is a lot for "first session"
Migration guide	518	Returning user	🔴 Too long	9 scenarios + troubleshooting — wall of text
ORPHAN: choose-your-interface.md	174	New user	—	Not in navigation, overlaps with choosing-your-path

Guide (8 pages in nav, 3 orphans)

Page	Lines	Audience	Length	Notes
Tips & Tricks	91	All users	✅ Good	Concise, scannable
Sample prompts	153	All users	✅ Good	Useful reference
Personal squad	326	Intermediate	⚠️ Long	9 use cases is thorough but could trim
Interactive shell	343	All users	⚠️ Long	Detailed but could be split
Extensibility	130	Advanced	✅ Good	Clean decision tree
Building extensions	126	Advanced	✅ Good
Contributing	311	Contributors	✅ OK
Contributors	205	Community	✅ OK
ORPHAN: build-autonomous-agent.md	537	Advanced	🔴 Too long	Not in navigation
ORPHAN: faq.md	277	All users	—	Not in navigation — FAQ is high-value, should be visible
ORPHAN: github-auth-setup.md	190	New user	—	Not in navigation

Features (33 pages in nav, 4 orphans)

Page	Lines	Audience	Length	Notes
Team setup	139	New user	✅ Good	Has duplicate "How Init Works" H2
Work routing	171	Intermediate	✅ Good	Has duplicate "Routing Strategies" H2
Model selection	189	Intermediate	✅ Good
Response modes	132	Intermediate	✅ Good
Parallel execution	177	Intermediate	✅ Good	Has duplicate "How Parallel Execution Works" H2
Memory	166	Intermediate	✅ Good
Skills	139	Intermediate	✅ Good
Directives	184	Intermediate	✅ Good	Has duplicate "How Directives Work" H2
Ceremonies	136	Intermediate	✅ Good
Reviewer protocol	197	Intermediate	✅ Good
GitHub issues	163	Intermediate	✅ Good
GitLab issues	197	Intermediate	✅ Good
Labels & triage	151	Intermediate	✅ Good
PRD mode	124	Advanced	✅ Good
Project boards	157	Intermediate	✅ Good
Ralph	276	Intermediate	⚠️ Borderline
@copilot coding agent	221	Intermediate	✅ Good
Human team members	134	Intermediate	✅ Good
Consult mode	263	Intermediate	✅ Good
Remote control	326	Advanced	⚠️ Long
VS Code	212	All users	✅ Good
Git worktrees	195	Advanced	✅ Good
Export & import	126	Intermediate	✅ Good
Upstream inheritance	410	Advanced	🔴 Too long
Marketplace	100	Intermediate	✅ Good
Plugins	430	Advanced	🔴 Too long
MCP	479	Advanced	🔴 Too long
Notifications	511	Advanced	🔴 Too long
Enterprise platforms	187	Enterprise	✅ Good
Squad RC	478	Advanced	🔴 Too long
Streams	148	Advanced	✅ Good	⚠️ Nav title "Streams" but content calls them "SubSquads"
Distributed mesh	318	Advanced	⚠️ Long
Capability routing	76	Advanced	✅ Concise
Rate limiting	76	Advanced	✅ Concise
KEDA autoscaling	83	Advanced	✅ Concise
ORPHAN: built-in-roles.md	95	New user	—	Not in navigation
ORPHAN: context-hygiene.md	130	Intermediate	—	Not in navigation
ORPHAN: cost-tracking.md	89	All users	—	Not in navigation
ORPHAN: issue-templates.md	348	Intermediate	—	Not in navigation

Reference (7 pages in nav, 1 orphan)

Page	Lines	Audience	Length	Notes
CLI	318	All users	⚠️ Long	Comprehensive but dense
SDK	653	Advanced	🔴 Too long	Massive — needs chunking or auto-generation
SDK API reference	426	Advanced	🔴 Too long
SDK integration	114	Advanced	✅ Good
Tools & hooks	114	Advanced	✅ Good
Config	207	All users	✅ Good
Glossary	39	All users	⚠️ Too short	Only 39 lines for a glossary — many terms missing
ORPHAN: vscode-troubleshooting.md	107	All users	—	Not in navigation

Scenarios (25 pages in nav)

Page	Lines	Audience	Length	Notes
Existing repo	177	New user	✅ Good
New project	170	New user	✅ Good
Solo developer	166	New user	✅ Good
Issue-driven dev	200	Intermediate	✅ Good
Monorepo	273	Advanced	✅ OK
CI/CD integration	223	Advanced	✅ Good
Team of humans	234	Intermediate	✅ Good
Large codebase	220	Advanced	✅ Good
Open source	277	Intermediate	✅ Good
Multiple squads	177	Advanced	✅ Good
Keep my squad	240	Intermediate	✅ Good
Mid-project	256	Intermediate	✅ Good
Upgrading	155	Returning	✅ Good
Multi-codespace	127	Advanced	✅ Good
Private repos	215	Intermediate	✅ Good
Cross-org auth	257	Enterprise	✅ Good
Team portability	146	Intermediate	✅ Good
Team state storage	329	Advanced	⚠️ Long
Switching models	233	Intermediate	✅ Good
Release process	357	Advanced	⚠️ Long
Scaling workstreams	168	Advanced	✅ Good
Client compatibility	272	All users	✅ OK
Remote Q&A	85	All users	✅ Concise
Disaster recovery	294	All users	⚠️ Long
Troubleshooting	158	All users	✅ Good
Aspire dashboard	319	Advanced	⚠️ Long

Concepts (6 pages in nav)

Page	Lines	Audience	Length	Notes
Architecture	70	All users	✅ Great	Lean, no handwaving — exemplary
Your team	347	New/intermediate	⚠️ Long	Heavy overlap with features/team-setup
Memory & knowledge	292	New/intermediate	⚠️ Long	Heavy overlap with features/memory and features/directives
Parallel work	363	Intermediate	⚠️ Long	Overlaps with features/parallel-execution
GitHub workflow	266	Intermediate	✅ OK
Portability	354	Intermediate	⚠️ Long

Cookbook (1 page in nav)

Page	Lines	Audience	Length	Notes
Recipes	220	All users	✅ Good

Standalone pages (4 in nav)

Page	Lines	Audience	Length	Notes
What's new	202	All users	✅ Good
SDK-first mode	661	Advanced	🔴 Too long	Longest page in the docs
Community	77	All users	✅ Good
Insider program	160	All users	✅ Good

Root-level orphans (not in any section or standalone nav)

Page	Lines	Notes
guide.md	564	🔴 Mega-page, not in nav, duplicates guide section content
sample-prompts.md	412	Duplicates guide/sample-prompts.md
tips-and-tricks.md	640	🔴 Duplicates guide/tips-and-tricks.md at 7× the length
tour-first-session.md	273	Likely superseded by get-started/first-session.md
tour-github-issues.md	199	Not linked anywhere
tour-gitlab-issues.md	236	Not linked anywhere

---

2. Content gaps

Features present in squad.agent.md or codebase but missing or unlisted in documentation navigation:

Gap	Status	Recommendation
FAQ	File exists (guide/faq.md, 277 lines) but not in nav	Add to Guide section — FAQs are high-value for new users
Built-in roles catalog	File exists (features/built-in-roles.md) but not in nav	Add to Features section or merge into team-setup
Context hygiene / squad nap	File exists (features/context-hygiene.md) but not in nav	Add to Features section — important maintenance command
Cost tracking	File exists (features/cost-tracking.md) but not in nav	Add to Features or merge into model-selection
Issue templates	File exists (features/issue-templates.md, 348 lines) but not in nav	Add to Features section
GitHub auth setup	File exists (guide/github-auth-setup.md) but not in nav	Add to Guide or Get Started — auth setup is a common blocker
Build autonomous agent	File exists (guide/build-autonomous-agent.md, 537 lines) but not in nav	Add to Guide section
VS Code troubleshooting	File exists (reference/vscode-troubleshooting.md) but not in nav	Add to Reference or link from VS Code feature page
Casting system	Described in squad.agent.md but no dedicated docs page	Consider adding a concepts or features page
Scribe agent	Mentioned everywhere but no dedicated page explaining Scribe behavior	Add to Concepts or Features
squad doctor command	Documented in CLI reference but deserves a troubleshooting link	Cross-link from troubleshooting scenario page

---

3. Redundancy and duplication

Critical duplications

Source A	Source B	Overlap
concepts/memory-and-knowledge.md (292 lines)	features/memory.md (166 lines) + features/directives.md (184 lines)	Heavy. Memory architecture, decision flow, skills overview, progressive summarization all covered in both concept and feature pages. The concept page is nearly a superset.
concepts/your-team.md (347 lines)	features/team-setup.md (139 lines)	Heavy. Init flow, default composition table, file structure, customization after init — all duplicated. The concept page is a superset of the feature page.
concepts/parallel-work.md (363 lines)	features/parallel-execution.md (177 lines)	Moderate. Fan-out pattern, sync vs background, reviewer gates, deadlock handling all in both.
Root tips-and-tricks.md (640 lines)	guide/tips-and-tricks.md (91 lines)	Redundant files. Root version is 7× longer and not in navigation.
Root sample-prompts.md (412 lines)	guide/sample-prompts.md (153 lines)	Redundant files. Root version is not in navigation.
Root guide.md (564 lines)	Entire Guide section	Redundant file. Mega-page duplicating the section.
get-started/choose-your-interface.md	get-started/choosing-your-path.md	Near-duplicate. Same concept, different file.

Duplicated headings within pages (copy-paste artifacts)

These pages have the same H2 header appearing twice, with content repeated or fragmented:

Page	Duplicated heading
features/team-setup.md	## How Init Works (lines 24 and 33)
features/routing.md	## Routing Strategies (lines 25 and 29)
features/parallel-execution.md	## How Parallel Execution Works (lines 27 and 29)
features/directives.md	## How Directives Work (lines 25 and 29)

These are bugs — likely from a merge or automated generation pass. Each should be deduplicated.

---

4. Style issues

Microsoft Style Guide compliance

Issue	Pages affected	MS Style Guide rule
Title-case headings	"Tips & Tricks", "Your First Session", "Quick Start" — some pages use title case, most use sentence case	Sentence case for all headings
Ampersand in headings	"Tips & Tricks", "Labels & Triage", "Tools & Hooks"	Spell out "and" in headings
Inconsistent "Try this" callout	~60% of feature pages have "Try this:" box, ~40% don't	Standardize — either all pages get it or none
Experimental banner	Every page repeats > ⚠️ **Experimental** — Squad is alpha software...	Consider a site-wide banner instead of per-page repetition
Agent names in examples	Mix of "Fenster/Hockney/McManus" (old universe) and "Ripley/Dallas/Kane" (Apollo/Alien) and "Neo/Trinity/Morpheus" (Matrix)	Standardize examples to current universe (Apollo 13 per decisions.md) or use generic role names
Passive voice	"Results come back labeled by agent" (first-session), "Skills are shared across the whole team" (skills) — occasional passive	Active voice preferred: "Squad returns results labeled by agent"

Content discipline violations

Issue	Details
"Commit .squad/" repeated everywhere	Appears in: first-session, tips-and-tricks, memory, skills, concepts/your-team, concepts/memory-and-knowledge, personal-squad, existing-repo. Say it once in a canonical location and link.
Installation instructions repeated	Quick start, installation, first-session, existing-repo, personal-squad, CLI reference all have install commands. Should be one canonical install page with links.
Personal squad platform table duplicated	Appears identically in installation.md and personal-squad.md. One canonical location, link from other.

---

5. Ranked recommendations

P0 — Fix now (quality bugs)

1. Remove duplicated H2 headings in team-setup, routing, parallel-execution, directives. These are copy-paste bugs that break document structure.
2. Delete or redirect root orphans (guide.md, tips-and-tricks.md, sample-prompts.md, tour-*.md). They're not in nav, duplicate content, and will confuse search engines if the site is indexed.
3. Fix "Streams" title mismatch. Nav says "Streams" but the page content calls them "SubSquads." Pick one name and use it consistently.

P1 — Add to navigation (missing high-value content)

4. Add FAQ to Guide section (guide/faq.md). FAQs are one of the most-visited pages on any docs site. Having one written but hidden is a missed opportunity.
5. Add context hygiene / squad nap to Features. Users need to know about maintenance commands.
6. Add GitHub auth setup to Guide or Get Started. Auth is the docs: add feature pages for link, nap, and scrub-emails commands #1 setup blocker.
7. Add VS Code troubleshooting to Reference. Link from the VS Code feature page.
8. Add cost-tracking, built-in-roles, issue-templates to nav or merge into existing pages.

P2 — Reduce duplication (content discipline)

9. Establish concept-vs-feature pattern. Concept pages should explain why and how it works conceptually. Feature pages should be how to use it — prompts, config, reference. Currently, concept pages duplicate feature pages nearly verbatim. Proposed rule: Concepts = explanation + architecture. Features = usage + configuration. Concept pages should link to feature pages for "how to use" details, not repeat them.
10. Canonicalize repeated content. "Commit .squad/", install instructions, and platform tables should each live in one place. All other mentions should link, not duplicate.
11. Merge choose-your-interface.md into choosing-your-path.md and delete the orphan.

P3 — Style consistency

12. Sentence-case all headings. Audit every page. Replace "Tips & Tricks" → "Tips and tricks", etc.
13. Standardize "Try this" callout. Either add it to all feature/guide pages or remove it from inconsistent ones. I'd recommend keeping it — it's a great progressive disclosure pattern.
14. Standardize agent names in examples. Use current Apollo 13 universe names or generic role names ("your Lead", "your Backend dev") so examples don't age when universe changes.
15. Replace per-page experimental banner with a site-wide notice. Repeating the same 15 words on every page wastes vertical space and trains users to ignore it.

P4 — Length and conciseness

16. Break up pages over 400 lines. Top offenders: sdk-first-mode.md (661), reference/sdk.md (653), migration.md (518), notifications.md (511), mcp.md (479), squad-rc.md (478), plugins.md (430). These need chunking, collapsible sections, or splitting into sub-pages.
17. Trim the Glossary or expand it. At 39 lines it's too thin to be useful. Either flesh it out with all Squad-specific terms (SubSquad, casting, billboard, mesh, directive, skill, ceremony, etc.) or remove it until it's ready.
18. Tighten first-session.md. 303 lines for a "your first session" walkthrough is long. Consider splitting the export section (step 9) into its own page.

---

Summary stats

Metric	Count
Total pages on disk	83
Pages in navigation	72
Orphaned pages (not in nav)	11
Pages over 400 lines (🔴 too long)	10
Pages with duplicate H2 bugs	4
Major content duplications	7 pairs
Undocumented features (in nav)	0
Documented but unlisted features	8+

---

This audit covers content quality only. Flight is handling IA, navigation structure, and information architecture in a parallel analysis on the same issue.

[diberry]

✅ P0 Items Completed

All P0 items from the content audit and IA review are fixed and shipped as bradygaster/squad PR (pending creation).

Done:

• Duplicate H2 headings — removed from 10 pages (team-setup, routing, parallel-execution, directives, notifications, plugins, prd-mode, worktrees, private-repos, routing)
• Orphan pages — 6 deleted (guide.md, sample-prompts.md, tips-and-tricks.md, tour-first-session.md, tour-github-issues.md, tour-gitlab-issues.md)
• Streams title mismatch — fixed (SubSquads → Streams)
• Dangling links — fixed in gitlab-issues.md and personal-squad.md
• Regression tests — 3 new tests guard against future regressions (duplicate H2, orphan pages, nav/title mismatch)

Remaining (P1-P4):

• P1: Wire 10 KNOWN_ORPHAN pages into navigation or delete
• P1: Resolve 7 KNOWN_MISMATCH nav/title pairs
• P2: Features section sub-grouping (33 flat pages → logical groups)
• P2: Move Concepts above Features in nav order
• P3: Content deduplication (7 pairs identified)
• P4: Conciseness review across all pages