[bradygaster]

Why

Follow-up from this morning's PR triage sweep. I audited the 16 merged PRs for doc drift; most were clean, but one real gap surfaced.

squad upgrade backs up locally customized Squad-owned files to <file>.local-backup before overwriting them — and #1709 (merged this morning) extended that behavior to workflow files. That behavior was only ever recorded in .squad/decisions.md. It appeared nowhere in user-facing docs, so a user who customized squad.agent.md or a Squad-managed workflow would see their file silently replaced and have no documented way to know a backup existed.

What changed

docs/src/content/docs/features/self-upgrade.md — new Your Customizations Are Backed Up subsection under Auto-Refresh Repo Templates:

• Which files are covered — .github/agents/squad.agent.md and the Squad-managed workflows
• Sample warning output and how to restore from a backup
• Version stamps are stripped before comparison, so a version-line-only diff isn't treated as a customization (upgrade.ts:250-253)
• Only the most recent backup is kept — the path is fixed, so re-customizing and upgrading again overwrites it (upgrade.ts:261, :473)
• Backups aren't gitignored, so they linger as untracked files
• --dry-run previews the squad.agent.md backup only — it returns at upgrade.ts:1137, before writeWorkflowFile runs, so customized workflows are not flagged

docs/src/content/docs/reference/cli.md — one-line cross-reference on the squad upgrade row for discoverability.

Verification

Every claim was traced to source rather than inferred:

Claim	Source
--dry-run is a real flag	cli-entry.ts:413
Version stamp stripped before compare	upgrade.ts:250-253
Agent backup prints restore instructions	upgrade.ts:262-263
Workflow backup warns only, no restore line	upgrade.ts:474
Dry-run returns before workflow files	upgrade.ts:1137
.local-backup not in .gitignore	git grep — no match

I initially wrote that --dry-run shows all files that would be backed up, then found the early return at :1137 and corrected it. The doc now says what the code actually does.

Follow-up worth considering (not in this PR)

*.local-backup isn't in .gitignore, and ensureGitignore() in upgrade.ts doesn't add it. Since backups land in .github/workflows/, a careless git add -A would commit them. Adding the entry is a one-liner in product source — it needs a changeset and is out of scope for a docs PR, so I've documented the sharp edge instead. Happy to open a separate issue if you want it fixed.

Notes

• Docs-only — no changeset required (changelog-gate only applies to packages/*/src/)
• Also leaves the pre-existing stale parenthetical at line 122 about --skip-repo-upgrade untouched — out of scope, but flagging it since it admits the flag may not exist

[github-actions]

🟢 Impact Analysis — PR #1843

Risk tier: 🟢 LOW

📊 Summary

Metric	Count
Files changed	2
Files added	0
Files modified	2
Files deleted	0
Modules touched	1

🎯 Risk Factors

• 2 files changed (≤5 → LOW)
• 1 module(s) touched (≤1 → LOW)

📦 Modules Affected

docs (2 files)

• docs/src/content/docs/features/self-upgrade.md
• docs/src/content/docs/reference/cli.md

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 12776c6

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	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	No merge conflicts
✅	Copilot threads resolved	No Copilot review threads
❌	CI passing	1 check(s) still running

Files Changed (2 files, +27 −1)

File	+/−
docs/src/content/docs/features/self-upgrade.md	+26 −0
docs/src/content/docs/reference/cli.md	+1 −1

Total: +27 −1

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[Copilot]

🟢 Approval recommended

The changes are docs-only, consistent with the current implementation, and introduce no functional risk.

Pull request overview

Documents squad upgrade’s behavior of backing up locally customized Squad-owned files to <file>.local-backup (including workflows), improving user discoverability and recovery guidance during upgrades.

Changes:

• Adds a new “Your Customizations Are Backed Up” subsection explaining what gets backed up, how to restore, and important edge cases (version-stamp comparison, single-backup overwrite, and untracked-file behavior).
• Adds a one-line CLI reference cross-note on squad upgrade to surface the backup behavior where users browse commands.

File summaries

File	Description
docs/src/content/docs/features/self-upgrade.md	Adds a dedicated subsection describing .local-backup behavior, examples, and dry-run limitations.
docs/src/content/docs/reference/cli.md	Adds a brief note to the squad upgrade command entry about .local-backup backups for customized files.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.