docs: comprehensive Squad troubleshooting guide#76
Closed
Conversation
Fork-specific workflow skills for PR hygiene: - fork-first-pipeline: review on fork before opening upstream PRs - bleed-check: twice-daily cross-branch audit for stowaway files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds Step 5.5 REBASE with guidance on rebasing feature branches against origin/dev to avoid full-file rewrites on shared files. Includes Shared File Strategy for surgical additions and When Rebase Fails recovery steps. Updates anti-patterns table to flag 'Skip rebase before upstream'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…, conventions) - Fork-first-pipeline: Added serial branch operations warning, force-add note for gitignored skills, stale comments check - Bleed-check: Added high-risk shared files callout, convention gate checks, CI path debugging pattern Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Dual Reviewer Gate: both Flight and FIDO must approve - Convention Issues Are Blockers: /docs/ prefix, double blanks, table order, whitespace - Review→Fix→Re-review Loop: both reviewers must re-review after fixes - Reviewer Lockout: locked authors cannot self-fix after rejection - Known PAO Quirks: watch for .squad/ files, /docs/ prefix, verification before push - Review Comments: formal PR comment format and verdict options - Tamir Reviewer Rule: only on upstream PRs with source material - Commit Hygiene: one commit, amend fixups, force-push safely, verify before push Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
When a PR completes the full fork pipeline (Flight+FIDO approved, bleed check passed, squashed, rebased, moved to upstream targeting Brady's dev), the upstream PR should be undrafted immediately. The upstream PR is the final presentation — draft PRs signal incomplete work, but at this stage all iteration is finished on the fork. Add gh pr ready command to Step 7 (UPSTREAM) as the final action after opening the upstream PR. Add anti-pattern entry for leaving upstream PRs in draft. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Renamed nap-troubleshooting.md to squad-troubleshooting.md - Expanded with sections: Squad Init, Casting, Agent Spawning, CI/CD, Decisions & History - Added Quick Fixes table for common 1-line solutions - Updated navigation to reflect comprehensive guide - Kept existing nap content as dedicated section - Maintained cross-platform bash/PowerShell examples throughout Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diberry
force-pushed
the
squad/nap-troubleshooting-guide
branch
from
e687ced to
a84eec0
Compare
diberry
changed the title
diberry
added
squad:pr-needs-review
Owner
Author
|
Closing: Upstream already has troubleshooting.md. Verified against bradygaster/squad dev + main on 2026-04-01. |
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
1 participant
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.
Troubleshooting guide for squad nap — covers all 5 nap operations, common problems, thresholds, and diagnostic script.
Includes cross-platform (bash/PowerShell) commands for Windows and Unix-like systems.
Added to docs/src/navigation.ts in Scenarios section.