Repository navigation
docs: comprehensive docs overhaul — truth, voice, and organization - #1426
Closed
bradygaster wants to merge 2 commits into
Closed
bradygaster wants to merge 2 commits into
bradygaster wants to merge 2 commits into
Conversation
- Delete retired docs (personal-squad, remote-control, shell, REPL blog) - Remove experimental/alpha warnings from all docs - Remove all personal squad references across 11 files - Voice pass: augmentation over replacement language (~30 files) - Remove REPL/interactive shell references (~45 files) - Reorganize navigation: Core/Advanced/Infrastructure feature tiers - Fix CI test knownSections for new nav structure - Fix broken internal links to deleted pages Closes #1194 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
🔴 Impact Analysis — PR #1426Risk tier: 🔴 CRITICAL 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (133 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 2 commits — consider squashing before review |
| ❌ | Not in draft | PR is still in draft — mark as ready for review when done |
| ❌ | Branch up to date | dev is 66 commit(s) ahead — rebase recommended |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | No source files changed — changeset not required |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ❌ | No merge conflicts | Merge conflicts detected — resolve before review |
| ✅ | Copilot threads resolved | No Copilot review threads |
| ❌ | CI passing | 4 check(s) still running |
Files Changed (133 files, +1825 −9833)
| File | +/− |
|---|---|
docs/src/content/blog/001-wave-0-the-team-that-built-itself.md |
+0 −19 |
docs/src/content/blog/001a-the-squad-squad-problem.md |
+4 −26 |
docs/src/content/blog/001b-meet-the-squad.md |
+0 −30 |
docs/src/content/blog/001c-first-pr-amolchanov.md |
+0 −21 |
docs/src/content/blog/002-first-community-pr.md |
+0 −16 |
docs/src/content/blog/003-super-bowl-weekend.md |
+0 −16 |
docs/src/content/blog/004-v020-release.md |
+0 −25 |
docs/src/content/blog/005-v030-give-it-a-brain.md |
+0 −32 |
docs/src/content/blog/006-first-external-deployment.md |
+0 −26 |
docs/src/content/blog/007-first-video-coverage.md |
+0 −23 |
docs/src/content/blog/008-v040-release.md |
+1 −24 |
docs/src/content/blog/009-v040-sprint-progress.md |
+0 −44 |
docs/src/content/blog/010-v041-patch-release.md |
+0 −16 |
docs/src/content/blog/011-skills-system-learning-from-work.md |
+2 −69 |
docs/src/content/blog/012-trending-on-github.md |
+0 −31 |
docs/src/content/blog/013-the-replatform-begins.md |
+0 −23 |
docs/src/content/blog/014-wave-1-otel-and-aspire.md |
+0 −28 |
docs/src/content/blog/015-wave-2-the-repl-moment.md |
+0 −95 |
docs/src/content/blog/016-wave-3-docs-that-teach.md |
+0 −25 |
docs/src/content/blog/017-version-alignment.md |
+0 −28 |
docs/src/content/blog/018-the-adapter-chronicles.md |
+0 −30 |
docs/src/content/blog/019-shaynes-remote-mode.md |
+0 −30 |
docs/src/content/blog/020-docs-reborn.md |
+0 −30 |
docs/src/content/blog/021-the-migration.md |
+0 −67 |
docs/src/content/blog/022-welcome-to-the-new-squad.md |
+16 −234 |
docs/src/content/blog/024-v0823-release.md |
+1 −164 |
docs/src/content/blog/026-whats-new-ado-comms-subsquads.md |
+0 −32 |
docs/src/content/blog/027-v0825-release.md |
+0 −19 |
docs/src/content/blog/028-new-docs-site.md |
+0 −33 |
docs/src/content/blog/028-v090-whats-new.md |
+15 −116 |
docs/src/content/blog/029-upgrade-testing-at-scale.md |
+1 −38 |
docs/src/content/blog/030-v092-whats-coming.md |
+0 −50 |
docs/src/content/blog/031-state-backends.md |
+1 −32 |
docs/src/content/blog/watch-monitor.md |
+5 −45 |
docs/src/content/docs/concepts/architecture.md |
+49 −71 |
docs/src/content/docs/concepts/github-workflow.md |
+1 −63 |
docs/src/content/docs/concepts/memory-and-knowledge.md |
+0 −74 |
docs/src/content/docs/concepts/parallel-work.md |
+3 −94 |
docs/src/content/docs/concepts/portability.md |
+0 −85 |
docs/src/content/docs/concepts/your-team.md |
+3 −79 |
docs/src/content/docs/cookbook/recipes.md |
+1 −81 |
docs/src/content/docs/features/capability-routing.md |
+54 −76 |
docs/src/content/docs/features/ceremonies.md |
+0 −42 |
docs/src/content/docs/features/cleanup.md |
+1 −42 |
docs/src/content/docs/features/consult-mode.md |
+18 −93 |
docs/src/content/docs/features/context-hygiene.md |
+93 −130 |
docs/src/content/docs/features/coordinator-as-agent-export.md |
+0 −53 |
docs/src/content/docs/features/copilot-coding-agent.md |
+5 −68 |
docs/src/content/docs/features/copilot-mcp-trust.md |
+0 −26 |
docs/src/content/docs/features/cost-tracking.md |
+69 −89 |
| ... | +83 more files |
Total: +1825 −9833
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
This was referenced Jun 30, 2026
Skills documented as added in 0.10.0 are not installed; tiered-memory provenance is fabricated
#1264
Closed
tamirdresher
reviewed
Jul 3, 2026
tamirdresher
left a comment
tamirdresher
left a comment
Collaborator
There was a problem hiding this comment.
Nice cleanup — the retired content removal and voice pass look great.
One small suggestion: in the "Try this:" quick-start block at the top of installation.md, consider changing bare squad to squad --version as the first thing to run after install. Running bare squad launches the full interactive experience which can be disorienting for someone who just wants to confirm the install worked. The Verify section further down already says squad --version — making the top block consistent would help first-timers.
Contributor
|
👋 Friendly nudge — this PR has had no activity for 7 days. What needs attention:
If this PR is abandoned, please close it. If it's blocked on something external, leave a comment so the team knows. |
Collaborator
|
@bradygaster — following up on this PR's current state:
How would you like to proceed? Two directions that would both unblock review — no preference from me, just want your steer:
Whichever you pick, happy to help move it forward. |
Contributor
|
👋 Friendly nudge — this PR has had no activity for 7 days. What needs attention:
If this PR is abandoned, please close it. If it's blocked on something external, leave a comment so the team knows. |
Contributor
|
👋 Friendly nudge — this PR has had no activity for 7 days. What needs attention:
If this PR is abandoned, please close it. If it's blocked on something external, leave a comment so the team knows. |
bradygaster
marked this pull request as draft
July 27, 2026 18:09
Collaborator
Author
|
Returning this to draft per the approved triage plan. Current blockers remain: merge conflicts against dev, failing docs-quality, overlap with already-merged #1466, and a 133-file surface too large for a reliable single review. Recommended path: rebase, enumerate/fix docs-quality failures, resolve the #1466 overlap, then split additive blog/content work from reference/feature-doc rewrites before requesting review again. |
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This was referenced Aug 3, 2026
bradygaster
added a commit
that referenced
this pull request
Aug 3, 2026
…erface canonical (WS-D) - Fix installation.md 'Try this:' block: bare 'squad' → 'squad --version' (addresses tamirdresher review comment from #1426) - Fix first-session.md: bare 'squad' → 'squad init' in all Try this and step code blocks (REPL-era artifact) - Remove⚠️ Experimental banners from all get-started files - Remove deprecated Interactive shell/REPL sections from choose-your-interface.md - Delete choosing-your-path.md (no inbound links; content covered by choose-your-interface.md) - Add choose-your-interface.md to Guides nav section - Apply WS-B nav restructure (depends on squad/1426-b-concepts-nav merging first) Supersedes part of #1426 Working as PAO (DevRel) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Collaborator
Author
Superseded by focused PRsThis PR has been replaced by four focused, reviewed PRs that each landed cleanly into
Real-world docs gaps are now tracked under umbrella issue #1564 with children #1565–#1569. Closing this PR without merging. |
pull Bot
pushed a commit
to nagyist/squad
that referenced
this pull request
Aug 3, 2026
…und (WS-A) - Remove⚠️ Experimental banners from all 34 blog posts - Replace hire/fire employment metaphors with cast/join language throughout - Replace 'autonomous' with 'background' or 'guided' framing - Delete 015-wave-2-the-repl-moment.md (REPL-era content; confirmed present on dev, deletion intentional) - Fix blog 031 passive wording: 'no human review needed' → 'no ceremony required' - Add historical framing note to blog 016 (first docs overhaul) - Fix contributor call-to-action in blog 028: 'hiring agents' → 'looking for contributors' Supersedes part of github#1426 Working as PAO (DevRel) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
pull Bot
pushed a commit
to nagyist/squad
that referenced
this pull request
Aug 3, 2026
- Remove⚠️ Experimental banners from all 6 concepts pages - Fix 'Fully unattended' → 'Event-driven' for cloud heartbeat in github-workflow.md - Restructure navigation.ts: Get Started 3 items, Concepts at position 2, Features split Core/Advanced/Infrastructure - Delete features/remote-control.md (replaced by features/squad-rc.md) - Delete guide/personal-squad.md and guide/shell.md (REPL/global-mode artifacts) - Update docs/tests/build-output.test.mjs knownSections to match new nav structure Supersedes part of github#1426 Working as PAO (DevRel) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
pull Bot
pushed a commit
to nagyist/squad
that referenced
this pull request
Aug 3, 2026
… (WS-C) - Rewrite features/prd-mode.md: ingestion/analysis only, removes 'write a PRD for me' framing - Rewrite scenarios/team-state-storage.md: replace .ai-team/ with .squad/, document local/orphan/two-layer backends and squad init --state-backend, remove outdated worktree/submodule strategies - Update features/state-backends.md with two-layer details, git-notes deprecation note, migration guidance - Document .squad/ralph-instructions.md escape hatch in features/ralph.md Related to github#1314 (docs recovery — full template/TEMPLATE_MANIFEST work tracked separately in github#1314) Closes github#1186 Closes github#1194 Supersedes part of github#1426 Working as PAO (DevRel) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Complete documentation overhaul addressing accuracy, voice/tone, organization, and open issues. Every doc and blog post was audited against the 0.11.0 codebase.
Changes
Retired Features Removed
guide/personal-squad.md(feature retired)features/remote-control.md(deprecatedsquad start)guide/shell.md(REPL deprioritized)blog/015-wave-2-the-repl-moment.md(REPL blog)Experimental Warnings Removed
⚠️ Experimental — alpha softwarefrom 122 filesVoice Pass — Augmentation Over Replacement
Navigation Reorganization
docs/tests/build-output.test.mjsknownSectionsIssue Fixes
.squad/config.jsononly)Write a PRD for…) but spec only supports ingestion #1186 — PRD Mode rewritten as ingestion/analysis (not authoring).squad/ralph-instructions.mdis an undocumented escape hatch insquad watch --execute— document it or remove it #1314 — Documented.squad/ralph-instructions.mdescape hatchBroken Links Fixed
remote-control.md→squad-rc.mdCloses
Closes #1194, closes #1400, closes #1264, closes #1186, closes #1314