From abacce5807e5adff6c46db7f4b2021d39dd370ed Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 13:40:09 -0700 Subject: [PATCH 1/6] chore: add fork-first pipeline and bleed-check skills 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> --- .copilot/skills/bleed-check/SKILL.md | 108 +++++++++++++++++++++ .squad/skills/fork-first-pipeline/SKILL.md | 94 ++++++++++++++++++ 2 files changed, 202 insertions(+) create mode 100644 .copilot/skills/bleed-check/SKILL.md create mode 100644 .squad/skills/fork-first-pipeline/SKILL.md diff --git a/.copilot/skills/bleed-check/SKILL.md b/.copilot/skills/bleed-check/SKILL.md new file mode 100644 index 000000000..ff8064531 --- /dev/null +++ b/.copilot/skills/bleed-check/SKILL.md @@ -0,0 +1,108 @@ +# Bleed-Check: Cross-Branch Audit + +## Confidence +High + +## Domain +Periodic cross-branch bleed audits, stowaway file detection + +## Problem Statement +Features developed on forks can accidentally include files intended for \.squad/\, docs, or unrelated purposes. These "stowaway" files pollute the upstream repository if not caught before PR merge. A periodic audit across all open PRs by a contributor identifies and flags these stragglers before they reach main. + +## Trigger + +- **Scheduled**: Twice per session day (morning and afternoon sweeps) +- **Proactive**: If >4 hours since last check, coordinator offers proactive bleed audit reminder + +## Scope + +All open PRs by **diberry** targeting **bradygaster/squad** + +Query: +\\\ash +gh pr list --author diberry --repo bradygaster/squad --base dev --state open +\\\ + +## Process + +### 1. List PRs +Fetch all open PRs from diberry targeting bradygaster/squad. + +### 2. For Each PR: Check File List +Retrieve the file list: +\\\ash +gh pr view {pr-number} --repo bradygaster/squad --json files +\\\ + +### 3. Flag Stowaways +Check each file against the PR's stated purpose (from title/description). Red flags: + +| Red Flag | Example | Why It's Bad | +|---|---|---| +| \.squad/\ files | \.squad/decisions/...\, \.squad/agents/...\ | Should not ship in app PRs | +| Navigation entries | \.squad/routing.md\ changes | Wrong PR can cause nav breakage | +| Test expectations | \.squad/agents/*/expected-output\ | Unmaintainable across PRs | +| Full-file rewrites | Accidental large refactors | Out of scope, causes merge debt | +| Build artifacts | \dist/\, \uild/\, \.next/\ | Should be in \.gitignore\ | +| Root-level strays | Unexpected \.env.local\, \secrets.json\ | Likely accidental commits | + +### 4. Output Format: Emoji-Based Table + +\\\ +| PR # | Title | Status | Bleed? | Details | +|---|---|---|---|---| +| #42 | Add auth feature | 🟒 CLEAN | No | All files in scope | +| #43 | Refactor parser | πŸ”΄ BLEED | Yes | \.squad/routing.md\ found (stowaway) | +| #44 | Update docs | 🟒 CLEAN | No | Docs changes as intended | +\\\ + +Status indicators: +- 🟒 CLEAN: All files align with PR purpose +- πŸ”΄ BLEED: Stowaway files detected, PR needs cleanup + +## Coordinator Behavior + +The Copilot acting as coordinator: + +1. **Track Last Check Time**: Record timestamp of last bleed audit +2. **Proactive Reminders**: After 4+ hours, suggest: "Hey, time for a bleed check? Want me to audit your open PRs?" +3. **Detailed Reports**: Show emoji table with file-by-file breakdown +4. **Actionable Guidance**: If bleed detected, suggest: "Pull request #43 has \.squad/routing.md\ - should this be removed before merging?" + +## Session Integration + +- Check at start of session for any overnight bleeds +- Offer mid-session reminder if threshold exceeded +- Report findings before upstream PR opens +- Track frequency for team metrics + +## Example Session Flow + +\\\ +βœ“ Session starts + "Last bleed check was 6 hours ago. Want me to run an audit?" + [User: Yes] + +β†’ Auditing 4 open PRs by diberry... + | #42 | auth feature | 🟒 CLEAN | + | #43 | parser refactor | πŸ”΄ BLEED | .squad/routing.md detected | + | #44 | docs update | 🟒 CLEAN | + | #45 | ui polish | 🟒 CLEAN | + +⚠️ Found 1 bleed in PR #43. Recommend removing .squad/routing.md before merging. +\\\ + +## Files to Inspect + +- PR title and description (stated purpose) +- \gh pr view --json files\ output (file manifest) +- Commit diff per file (spot-check suspect files) +- PR body for merge strategy notes + +## Non-Bleed Scenarios + +NOT considered bleed: +- Legitimate test files for the PR feature +- README or CONTRIBUTING updates (if PR documents the change) +- New src/ files (app code is in scope) +- Configuration files directly related to the feature (tsconfig.json tweaks, etc.) diff --git a/.squad/skills/fork-first-pipeline/SKILL.md b/.squad/skills/fork-first-pipeline/SKILL.md new file mode 100644 index 000000000..758d244d4 --- /dev/null +++ b/.squad/skills/fork-first-pipeline/SKILL.md @@ -0,0 +1,94 @@ +# Fork-First PR Pipeline + +## Confidence +High + +## Domain +PR workflow, cross-fork collaboration + +## Problem Statement +PRs opened directly on the upstream repository get messy iteration in public. Code review feedback creates visible churn. Force-push history is exposed. This workflow keeps development clean by staging changes on the fork first, then opening a single clean upstream PR after review is complete. + +## 8-Step Pipeline + +\\\ +BRANCH β†’ FORK PR β†’ REVIEW β†’ FIX β†’ BLEED CHECK β†’ CLEAN β†’ UPSTREAM β†’ DONE +\\\ + +### Step 1: BRANCH +Create a feature branch locally: +\\\ash +git checkout -b squad/{issue-number}-{slug} +\\\ + +### Step 2: FORK PR +Push to fork and open PR **against your fork's dev branch**: +\\\ash +git push origin {branch-name} +gh pr create --base dev --draft # Opens on fork/dev, not upstream +\\\ + +### Step 3: REVIEW +Iterate on the fork PR with teammates. Collect feedback via review comments. This happens in your fork, not upstream. + +### Step 4: FIX +Address review comments. Commit changes directly to the feature branch (don't squash yet). + +### Step 5: BLEED CHECK +Run a bleed audit to verify no stowaway files are committed. Check for: +- \.squad/\ files (should not be in app PRs) +- Navigation entries for wrong PR +- Test expectations for wrong PR +- Full-file rewrites +- Build artifacts +- Root-level strays + +If bleed detected, fix on the feature branch. + +### Step 6: CLEAN +Prepare for upstream PR: +- Squash commits into logical units +- Clean up commit messages +- Remove any \.squad/\ files if present +- Verify no \/docs/\ prefix in titles +- Remove double blank lines from description + +### Step 7: UPSTREAM +Open PR on upstream repository against \radygaster/squad:dev\: +\\\ash +gh pr create --repo bradygaster/squad --base dev --fill +\\\ + +### Step 8: DONE +Upstream PR is merged. Close or keep fork PR for reference. + +## Anti-Patterns + +| Anti-Pattern | Why It Fails | Better Way | +|---|---|---| +| Open upstream PR before fork review complete | Public iteration, messy history | Complete review cycle on fork first | +| Force-push to upstream branch | Breaks links, confuses reviewers | Squash locally, push once | +| Skip bleed check | Stowaway files merge upstream | Always audit before upstream PR | +| Commit \.squad/\ files in app PRs | Repo pollution, merge conflicts | Exclude from staging, bleed check catches this | +| Open multiple PRs per feature | Fragmented review, merge chaos | One upstream PR per feature | + +## Pre-Upstream Gate Checklist + +Before opening the upstream PR, verify: + +- [ ] **Flight approval**: Fork PR merged into fork/dev +- [ ] **FIDO approval**: Code quality, tests pass, no security issues +- [ ] **Bleed check pass**: Zero stowaway files, no \.squad/\ commits +- [ ] **Squash commits**: 1-3 logical commits, not N from iteration +- [ ] **Clean description**: No double blank lines, clear problem/solution +- [ ] **No \.squad/\ files**: Excluded from commit entirely +- [ ] **No \/docs/\ prefix**: If docs changes, they go elsewhere +- [ ] **No double blank lines**: Markdown/description formatting clean + +## Workflow Summary + +This pipeline separates concerns: +- **Fork PR**: Messy iteration, team feedback, bleed capture +- **Upstream PR**: Clean, single-commit, ready-to-merge + +Result: Upstream PRs are lean, reviewed, and production-ready. From 46d25c99d5f32592917f91750c14185ed98ef701 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 13:42:25 -0700 Subject: [PATCH 2/6] chore: add rebase guidance to fork-first pipeline skill 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> --- .squad/skills/fork-first-pipeline/SKILL.md | 26 ++++++++++ .../content/docs/concepts/nap-vs-compact.md | 52 +++++++++++++++++++ .../content/docs/features/context-hygiene.md | 4 +- 3 files changed, 80 insertions(+), 2 deletions(-) create mode 100644 docs/src/content/docs/concepts/nap-vs-compact.md diff --git a/.squad/skills/fork-first-pipeline/SKILL.md b/.squad/skills/fork-first-pipeline/SKILL.md index 758d244d4..1bdfff754 100644 --- a/.squad/skills/fork-first-pipeline/SKILL.md +++ b/.squad/skills/fork-first-pipeline/SKILL.md @@ -45,6 +45,31 @@ Run a bleed audit to verify no stowaway files are committed. Check for: If bleed detected, fix on the feature branch. +### Step 5.5: REBASE +Before squashing for upstream, rebase the feature branch against `origin/dev` to avoid full-file rewrites: +\\\ash +git fetch origin dev +git rebase origin/dev +\\\ + +#### Shared File Strategy +For files shared across PRs (navigation.ts, test files, CI workflows): +- **Never** make full-file changes on feature branches +- **Always** reset to dev first, then make surgical additions: + \\\ash + git checkout origin/dev -- docs/src/navigation.ts + # Then manually add ONLY the entries for this PR's content + \\\ +- This prevents diffs that rewrite the entire file, which cause merge conflicts with every other PR + +#### When Rebase Fails +If rebase has conflicts on shared files: +1. `git rebase --abort` +2. Reset the shared files to dev: `git checkout origin/dev -- {file}` +3. Re-add only this PR's surgical changes +4. `git commit --amend --no-edit` +5. Continue with step 6 CLEAN + ### Step 6: CLEAN Prepare for upstream PR: - Squash commits into logical units @@ -71,6 +96,7 @@ Upstream PR is merged. Close or keep fork PR for reference. | Skip bleed check | Stowaway files merge upstream | Always audit before upstream PR | | Commit \.squad/\ files in app PRs | Repo pollution, merge conflicts | Exclude from staging, bleed check catches this | | Open multiple PRs per feature | Fragmented review, merge chaos | One upstream PR per feature | +| Skip rebase before upstream | Diverged branch creates full-file diffs | Always rebase against origin/dev before step 6 | ## Pre-Upstream Gate Checklist diff --git a/docs/src/content/docs/concepts/nap-vs-compact.md b/docs/src/content/docs/concepts/nap-vs-compact.md new file mode 100644 index 000000000..cd4b54f73 --- /dev/null +++ b/docs/src/content/docs/concepts/nap-vs-compact.md @@ -0,0 +1,52 @@ +--- +title: Nap vs /compact +description: How Squad nap and Copilot CLI /compact solve different memory problems at different layers. +--- + +# Nap vs /compact + +Users hit memory limits in two ways: the chat gets too big, or agent memory piles up over time. + +The pain shows up for users as slow agents, lost context, or token pressure β€” even though the fixes happen behind the scenes. + +## How each one works + +**Squad Nap** fixes a long-term team problem by archiving shared memory to disk. Nothing is lost, and future agents stay lean. + +**/compact** fixes a right-now chat problem by summarizing and freeing tokens. Original messages are gone. + +## Comparison + +| | Squad Nap | /compact | +|---|---|---| +| Purpose | Archive squad memory | Shrink current chat | +| Scope | Persistent, shared | Ephemeral, session-only | +| Method | Move full data to disk | Replace with summary | +| Logic | Size + age rules | One-pass LLM | +| Trigger | Thresholds hit | User or token pressure | +| Benefit | Future agents | Current conversation | +| Recovery | Full (archives exist) | None | +| Model | Filing cabinet | Whiteboard erase | + +## When to use each + +**Use `squad nap` when:** +- Your `.squad/` files are growing and agents feel slower +- You've completed a phase and want to archive old work +- You're preparing to spawn new agents (smaller state = cheaper spawns) +- You want to keep a permanent archive of past decisions (they go to `-archive.md`) + +**Use `/compact` when:** +- Your current conversation is getting long and token-heavy +- You want to continue the session but free up context space for new questions +- You're running out of conversation tokens within a single session +- You want a summary of your chat history before moving on + +## Using both together + +They're **not** mutually exclusive β€” use both in sequence for optimal team hygiene: + +1. **In your Squad session:** Tell the team to `take a nap`. This cleans up persistent state files, making future agent spawns lighter and faster. +2. **After the session:** If your conversation was long, use `/compact` in the CLI to summarize the transcript. This frees tokens for the next session. + +**Bottom line: /compact helps this conversation. Squad Nap helps every conversation after this.** diff --git a/docs/src/content/docs/features/context-hygiene.md b/docs/src/content/docs/features/context-hygiene.md index bef518244..2a3317834 100644 --- a/docs/src/content/docs/features/context-hygiene.md +++ b/docs/src/content/docs/features/context-hygiene.md @@ -24,7 +24,7 @@ Over multiple sessions, Squad's `.squad/` files grow β€” agent histories, decisi ## Nap -**What it does:** Summarizes accumulated work into smaller, more efficient memory files. This is the same as running `/compact` in the CLI or `squad nap` from the command line. +**What it does:** Summarizes accumulated work in `.squad/` team state files into smaller, more efficient memory files. This compresses your persistent team knowledge β€” agent histories, decisions, and logs across multiple sessions. When you tell the team to "take a nap," each agent: @@ -52,7 +52,7 @@ squad nap --deep # Thorough cleanup with recursive descent squad nap --dry-run # Preview what would be cleaned up ``` -In the interactive shell, use `/compact` for the same effect. +> **Note:** For session-level conversation compression, use `/compact` in the Copilot CLI interactive shell. See [Nap vs /compact](/concepts/nap-vs-compact) for the difference between team state cleanup and session transcript compression. --- From 44f992f158d3a50bfeaed034345269bb4578ac1e Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 14:03:20 -0700 Subject: [PATCH 3/6] chore: update skills with session learnings (serial ops, shared files, 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> --- .copilot/skills/bleed-check/SKILL.md | 37 ++++++++++++++++++++++ .squad/skills/fork-first-pipeline/SKILL.md | 17 ++++++++++ 2 files changed, 54 insertions(+) diff --git a/.copilot/skills/bleed-check/SKILL.md b/.copilot/skills/bleed-check/SKILL.md index ff8064531..f8f64e4fe 100644 --- a/.copilot/skills/bleed-check/SKILL.md +++ b/.copilot/skills/bleed-check/SKILL.md @@ -9,6 +9,16 @@ Periodic cross-branch bleed audits, stowaway file detection ## Problem Statement Features developed on forks can accidentally include files intended for \.squad/\, docs, or unrelated purposes. These "stowaway" files pollute the upstream repository if not caught before PR merge. A periodic audit across all open PRs by a contributor identifies and flags these stragglers before they reach main. +## High-Risk Shared Files + +**These files are the #1 bleed vectors** β€” they appear in almost every docs PR and are where cross-branch contamination happens most: + +- **`navigation.ts`** β€” contains site structure and nav entries for all features +- **`test/docs-build.test.ts`** β€” build verification tests that reference multiple PRs' output paths +- **`docs/` directories** β€” shared documentation structure + +**When checking these files, verify entries are ONLY for this PR's content β€” not entries from other concurrent PRs or stale previous runs. Flag full-file rewrites of these shared files β€” surgical additions only.** + ## Trigger - **Scheduled**: Twice per session day (morning and afternoon sweeps) @@ -46,6 +56,33 @@ Check each file against the PR's stated purpose (from title/description). Red fl | Build artifacts | \dist/\, \uild/\, \.next/\ | Should be in \.gitignore\ | | Root-level strays | Unexpected \.env.local\, \secrets.json\ | Likely accidental commits | +### 3.5: Convention Gate Checks + +While auditing files, also check for house-style violations. **These are blockers, not nits β€” per team directive.** + +| Convention | Rule | Blocker? | +|-----------|------|----------| +| Internal link format | Use bare paths like `/features/memory`, not `/docs/features/memory` | βœ… Yes | +| Blank lines | Single blank line between sections (not double) | βœ… Yes | +| Entry duplication | Each nav entry appears exactly once | βœ… Yes | +| Stale TDD comments | Clean up "RED PHASE", "TODO: implement", "WIP" markers before merge | βœ… Yes | + +### 3.6: CI Path Debugging Pattern + +When CI reports a step as successful but tests fail on a missing file, path mismatches often indicate cross-branch contamination or stale config: + +Example: CI says "generator succeeded β€” output at docs/public/" but the test looks for docs/dist/ and fails. + +**Check actual path**: +\\\ash +ls -la docs/public/ +ls -la docs/dist/ +grep "outDir" build.config.ts +grep "docs/dist" test/docs-build.test.ts +\\\ + +**Pattern**: Add `ls -la {expected-path}` verification steps when debugging CI file issues. This reveals if the build wrote to the wrong directory (often from stale config or entries from another PR). + ### 4. Output Format: Emoji-Based Table \\\ diff --git a/.squad/skills/fork-first-pipeline/SKILL.md b/.squad/skills/fork-first-pipeline/SKILL.md index 1bdfff754..e4caacd51 100644 --- a/.squad/skills/fork-first-pipeline/SKILL.md +++ b/.squad/skills/fork-first-pipeline/SKILL.md @@ -62,6 +62,17 @@ For files shared across PRs (navigation.ts, test files, CI workflows): \\\ - This prevents diffs that rewrite the entire file, which cause merge conflicts with every other PR +#### Serial Branch Operations β€” Critical Rule + +⚠️ **When multiple agents fix different PRs in parallel on the same physical repository (even if different branches), they all run `git checkout` in the same working tree.** This causes: +- Working tree conflicts (both agents try to update `.git/index` simultaneously) +- Commits landing on wrong branches (Agent A's commit lands on Agent B's branch) +- Race conditions (`.git/HEAD` and `.git/index` become inconsistent) + +**RULE: Bleed fixes across multiple PRs must be done SERIALLY (one at a time) unless using git worktrees.** Never launch parallel agents that checkout different branches in the same repo without worktrees. + +**Exception**: Use `git worktree add ../squad-195 -b squad/195-fix-issue origin/dev` to give each agent an isolated working directory. + #### When Rebase Fails If rebase has conflicts on shared files: 1. `git rebase --abort` @@ -75,9 +86,12 @@ Prepare for upstream PR: - Squash commits into logical units - Clean up commit messages - Remove any \.squad/\ files if present +- Check for stale TDD comments ("RED PHASE", "TODO: implement", "WIP") that no longer apply - Verify no \/docs/\ prefix in titles - Remove double blank lines from description +**Note on `.squad/skills/` files**: The `.squad/skills/` directory may be gitignored in some configurations. If you need to commit skill files to the fork, use `git add -f` to force them through, even if they match `.gitignore` patterns. + ### Step 7: UPSTREAM Open PR on upstream repository against \radygaster/squad:dev\: \\\ash @@ -97,6 +111,9 @@ Upstream PR is merged. Close or keep fork PR for reference. | Commit \.squad/\ files in app PRs | Repo pollution, merge conflicts | Exclude from staging, bleed check catches this | | Open multiple PRs per feature | Fragmented review, merge chaos | One upstream PR per feature | | Skip rebase before upstream | Diverged branch creates full-file diffs | Always rebase against origin/dev before step 6 | +| Parallel branch checkouts in same repo | Multiple agents switch branches simultaneously, causing working tree conflicts and commits landing on wrong branches | Use git worktrees or fix PRs serially | +| Forgetting to stash skill file updates | `.squad/skills/` files are gitignored, so they don't commit to the fork | Use `git add -f` when committing skill files | +| Leaving stale TDD comments in code | "RED PHASE", "TODO: implement" markers confuse reviewers after merge | Clean up all TDD markers before approval | ## Pre-Upstream Gate Checklist From 4f1c7326e5054f9c5aac9d1c36d05127b79b9d73 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 14:05:07 -0700 Subject: [PATCH 4/6] chore: add team review protocol to fork-first pipeline skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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> --- .squad/skills/fork-first-pipeline/SKILL.md | 81 ++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/.squad/skills/fork-first-pipeline/SKILL.md b/.squad/skills/fork-first-pipeline/SKILL.md index e4caacd51..ac2c92642 100644 --- a/.squad/skills/fork-first-pipeline/SKILL.md +++ b/.squad/skills/fork-first-pipeline/SKILL.md @@ -128,6 +128,87 @@ Before opening the upstream PR, verify: - [ ] **No \/docs/\ prefix**: If docs changes, they go elsewhere - [ ] **No double blank lines**: Markdown/description formatting clean +## Team Review Protocol + +The fork PR review phase enforces team-wide quality standards. These patterns are mandatory. + +### Dual Reviewer Gate +Every fork PR must be reviewed by **BOTH Flight (architecture)** and **FIDO (quality)** before approval. The rule: +- **Both APPROVE**: Ready to proceed +- **One APPROVE + One REJECT**: Not ready β€” re-review cycle required +- **No single-reviewer approvals**: A partial approval does not unblock + +Both reviewers must sign off in the same review round or in sequential re-review rounds (see Reviewβ†’Fixβ†’Re-review Loop below). + +### Convention Issues Are Blockers +The following are **NOT nits** β€” they are blockers per team directive. Flight and FIDO must flag these as `NEEDS FIXES`, never as "non-blocking notes": + +- **`/docs/` prefix in internal links**: Links like `/docs/features/memory` should be bare: `/features/memory`. The /docs/ prefix is stripped at build time; links must not include it. +- **Double blank lines**: Single blank line is house style. Two or more consecutive blank lines must be reduced to one. +- **Table ordering discontinuities**: If tables reference order (e.g., step 1, 2, 3), they must be sequential without gaps. +- **Whitespace violations**: Trailing spaces, tabs instead of spaces, or inconsistent indentation. + +When a reviewer finds any of these, the review verdict is **NEEDS FIXES** with findings documented. The author must correct all flagged conventions. + +### Reviewβ†’Fixβ†’Re-review Loop +After reviewers identify blockers: + +1. **Fix**: Author addresses all blocker comments on the feature branch (use `git commit --amend --no-edit` for fast-forward fixes, or new commits if refactoring is complex). +2. **Re-run reviews**: **Both Flight AND FIDO must re-review**, even if only one reviewer found issues. This ensures convention fixes don't introduce new problems. +3. **Loop until both APPROVE**: Repeat until both reviewers vote APPROVE. +4. **Bleed check**: After both APPROVE, proceed to Step 5 (bleed check). + +Do not skip to bleed check after a single reviewer fix. + +### Reviewer Lockout +If Flight rejects a fork PR, the original author is locked out from self-revising. A **different agent** must make the fix and commit it. This is enforced mechanically: + +- **Original author**: Locked from further commits on the feature branch after rejection. +- **Different agent** (e.g., Booster stepping in for PAO): Makes the fixes, commits, and force-pushes with `--force-with-lease`. +- **Re-review**: Both Flight and FIDO re-review the updated PR. + +This rule prevents single-agent fixation loops and ensures peer review diversity. + +### Known PAO Quirks (Watch for These) +If PAO is the author, Flight and FIDO should watch for: + +- **`.squad/` file creep**: PAO often includes `.squad/agents/pao/history.md` or other `.squad/` files in commits. These must be explicitly excluded via bleed check or pre-commit rules. +- **`/docs/` prefix overuse**: PAO tends to add `/docs/` prefix to all internal links. Every reviewer must instruct "use bare paths β€” no /docs/ prefix." +- **Force-push caution**: Before PAO pushes, verify `git diff --cached --stat` matches intent and `git diff --cached --diff-filter=D` shows zero unintended deletions. + +This is not a critique β€” it is a known pattern. Treat it as a checklist, not a personal issue. + +### Review Comments Posted on PR +Formal reviews are posted to the fork PR as: +``` +gh pr comment {pr-number} --body "REVIEW: {verdict} + +## Findings +{findings} + +## Summary +{summary}" +``` + +Verdict options: `APPROVE`, `NEEDS FIXES`, `REQUEST CHANGES`. + +Findings should reference specific files, line numbers, and convention violations. Summary should restate the path forward (re-review required, bleed check next, etc.). + +### Tamir Reviewer Rule +Only assign Tamir as a reviewer on **upstream PRs** where his original code PR is the source material for the content being documented. Do not add him to every upstream PR by default. On fork PRs, Flight and FIDO are the standard reviewers. + +### Commit Hygiene +To ensure clean histories: + +- **One commit per fork PR**: Squash all review iterations into a single logical commit before opening upstream PR. +- **Amend, don't create new commits**: Use `git commit --amend --no-edit` to fix blockers without adding commit count. +- **Force-push safely**: Use `--force-with-lease` to prevent accidental overwrites if teammates push simultaneously (rare in single-agent fork setup, but good practice). +- **Always verify before push**: + ``` + git diff --cached --stat # File count must match intent + git diff --cached --diff-filter=D # Should show zero unintended deletions + ``` + ## Workflow Summary This pipeline separates concerns: From eb6ba5ae35e72df78d5c7fdab2384266a3c64847 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 14:08:16 -0700 Subject: [PATCH 5/6] chore: add undraft rule to fork-first pipeline skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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> --- .squad/skills/fork-first-pipeline/SKILL.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/.squad/skills/fork-first-pipeline/SKILL.md b/.squad/skills/fork-first-pipeline/SKILL.md index ac2c92642..b66273b06 100644 --- a/.squad/skills/fork-first-pipeline/SKILL.md +++ b/.squad/skills/fork-first-pipeline/SKILL.md @@ -93,11 +93,17 @@ Prepare for upstream PR: **Note on `.squad/skills/` files**: The `.squad/skills/` directory may be gitignored in some configurations. If you need to commit skill files to the fork, use `git add -f` to force them through, even if they match `.gitignore` patterns. ### Step 7: UPSTREAM -Open PR on upstream repository against \radygaster/squad:dev\: -\\\ash +Open PR on upstream repository against radygaster/squad:dev: +\\\ash gh pr create --repo bradygaster/squad --base dev --fill \\\ +After the PR is created, undraft it to mark it ready for review. The upstream PR is the **final presentation** β€” it should not remain in draft: +\\\ash +gh pr ready {pr-number} --repo bradygaster/squad +\\\ + +The upstream PR signals completion of the fork pipeline. Leaving it in draft confuses reviewers β€” they may assume work is still in progress when iteration is already complete. ### Step 8: DONE Upstream PR is merged. Close or keep fork PR for reference. @@ -114,6 +120,7 @@ Upstream PR is merged. Close or keep fork PR for reference. | Parallel branch checkouts in same repo | Multiple agents switch branches simultaneously, causing working tree conflicts and commits landing on wrong branches | Use git worktrees or fix PRs serially | | Forgetting to stash skill file updates | `.squad/skills/` files are gitignored, so they don't commit to the fork | Use `git add -f` when committing skill files | | Leaving stale TDD comments in code | "RED PHASE", "TODO: implement" markers confuse reviewers after merge | Clean up all TDD markers before approval | +| Leave upstream PR in draft | Signals incomplete work when pipeline is done | Undraft upstream PR after opening β€” it's presentation-ready | ## Pre-Upstream Gate Checklist @@ -216,3 +223,5 @@ This pipeline separates concerns: - **Upstream PR**: Clean, single-commit, ready-to-merge Result: Upstream PRs are lean, reviewed, and production-ready. + + From a84eec022b432d506c2d7beda7094cfb09c087a7 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Sat, 28 Mar 2026 05:26:17 -0700 Subject: [PATCH 6/6] docs: comprehensive Squad troubleshooting guide - 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> --- .../docs/scenarios/squad-troubleshooting.md | 812 ++++++++++++++++++ docs/src/navigation.ts | 2 +- 2 files changed, 813 insertions(+), 1 deletion(-) create mode 100644 docs/src/content/docs/scenarios/squad-troubleshooting.md diff --git a/docs/src/content/docs/scenarios/squad-troubleshooting.md b/docs/src/content/docs/scenarios/squad-troubleshooting.md new file mode 100644 index 000000000..a941cc051 --- /dev/null +++ b/docs/src/content/docs/scenarios/squad-troubleshooting.md @@ -0,0 +1,812 @@ +--- +title: Squad Troubleshooting Guide +description: Comprehensive troubleshooting guide for Squad, covering initialization, casting, agent spawning, nap operations, CI/CD issues, and common quick fixes. +--- + +This guide covers Squad setup, execution, maintenance, and CI/CD issues. Start with the **Quick Fixes** table for common one-liner solutions, then dive into detailed troubleshooting for your specific problem. + +--- + +## Common Quick Fixes + +| Error | Cause | Fix | +|-------|-------|-----| +| `squad: command not found` | Squad CLI not installed | Run `npm install -g @bradygaster/squad-cli` or use `npx @bradygaster/squad-cli` | +| `No .squad/ directory found` | Not in a git repo or Squad not initialized | Run `git init` then `npx squad init` | +| `Cannot find agent "{name}"` | Agent doesn't exist | Check `.squad/team.md` roster or run `squad cast` | +| `gh: command not found` | GitHub CLI not installed | Install from [cli.github.com](https://cli.github.com/) then `gh auth login` | +| `Node.js version error` | Node.js version below v20 | Upgrade to v20+ (nvm: `nvm install --lts && nvm use --lts`) | +| `npx github:bradygaster/squad` hangs | SSH key not loaded | Run `eval "$(ssh-agent -s)" && ssh-add` then retry | +| `gh` auth fails | Not logged in or missing scopes | Run `gh auth login` then `gh auth refresh -s project` | +| `Squad agent not in /agent list` | squad.agent.md missing | Re-run `npx github:bradygaster/squad` | +| `Path errors on Windows` | Wrong shell | Use PowerShell or Git Bash (not cmd.exe) | + +--- + +## Squad Init Issues + +### Problem: "squad init fails" + +**Cause:** git not found, not in a git repository, or `.squad/` already exists. + +**Check 1: Is git installed and in PATH?** + +```bash +# macOS/Linux +which git + +# Windows +Get-Command git +``` + +**Check 2: Are you in a git repository?** + +```bash +# macOS/Linux +ls -la .git + +# Windows +Test-Path ".\.git" +``` + +If no `.git/` directory, initialize one: + +```bash +git init +``` + +**Check 3: Does .squad/ already exist?** + +```bash +# macOS/Linux +ls -la .squad/ + +# Windows +Get-Item -Path ".\.squad" -Force +``` + +If `.squad/` exists and you want to reinitialize, back it up first: + +```bash +# macOS/Linux +mv .squad/ .squad.bak + +# Windows +Move-Item -Path ".\.squad" -Destination ".\.squad.bak" +``` + +**Resolution:** Run `squad init` after ensuring git is set up and `.squad/` doesn't exist. + +--- + +### Problem: "Team not created after init" + +**Check:** Does `.squad/team.md` have a `## Members` section? + +```bash +# macOS/Linux +grep -n "## Members" .squad/team.md + +# Windows +Select-String -Path ".\.squad\team.md" -Pattern "## Members" +``` + +If missing, re-run `squad init` or manually add a Members section: + +```markdown +## Members + +- **Avery** (avery): Generalist agent +``` + +--- + +### Problem: ".gitattributes not created" + +**Check:** Merge drivers present? + +```bash +# macOS/Linux +grep -E "merge=union|merge=ours" .gitattributes + +# Windows +Select-String -Path ".\.gitattributes" -Pattern "merge=union|merge=ours" +``` + +**Resolution:** Re-run `squad init` which adds: + +``` +.squad/decisions.md merge=union +.squad/agents/*/history.md merge=union +``` + +--- + +## Casting Issues + +### Problem: "Agent names not from the same universe" + +**Cause:** Casting registry corrupted or mixing casting sources (e.g., AI-generated names mixed with book characters). + +**Check:** Is `.squad/casting/` configured? + +```bash +# macOS/Linux +ls -la .squad/casting/ + +# Windows +Get-ChildItem -Path ".\.squad\casting" +``` + +**Resolution:** Run `squad cast` to regenerate agent names from a consistent source. + +--- + +### Problem: "New agent gets a random name" + +**Cause:** `casting/` directory missing or not migrated from older Squad setup. + +**Check:** Is casting configured in squad.config.ts? + +```bash +# macOS/Linux +grep -A 5 "casting" squad.config.ts + +# Windows +Select-String -Path "squad.config.ts" -Pattern "casting" -A 5 +``` + +**Resolution:** + +1. Run migration: `squad migrate` +2. Re-run casting: `squad cast` + +--- + +### Problem: "CastingEngine failed" + +**Cause:** Universe of available names exhausted (> 999 agents registered). + +**Check:** How many agents are in the roster? + +```bash +# macOS/Linux +grep -c "^- " .squad/team.md + +# Windows +@(Select-String -Path ".\.squad\team.md" -Pattern "^- ").Count +``` + +**Resolution:** This is rare. If you have hundreds of agents, contact Squad maintainers. + +--- + +## Agent Spawning Issues + +### Problem: "Agent doesn't respond" + +**Cause:** Silent success bug β€” agent spawned successfully but didn't stream responses (~7-10% of background spawns). + +**Check 1: Is the agent in your roster?** + +```bash +# macOS/Linux +grep "{agent-name}" .squad/team.md + +# Windows +Select-String -Path ".\.squad\team.md" -Pattern "{agent-name}" +``` + +**Check 2: Check orchestration logs** + +```bash +# macOS/Linux +tail -100 .squad/orchestration-log/*.log + +# Windows +Get-Content (Get-ChildItem -Path ".\.squad\orchestration-log\*.log" | Sort-Object LastWriteTime -Desc | Select-Object -First 1).FullName -Tail 100 +``` + +**Resolution:** Re-run the command. If consistent, file an issue with logs attached. + +--- + +### Problem: "Agent can't find files" + +**Cause:** Wrong TEAM_ROOT or worktree path misconfiguration. + +**Check 1: Is TEAM_ROOT set?** + +```bash +# macOS/Linux +echo $TEAM_ROOT + +# Windows +echo $env:TEAM_ROOT +``` + +**Check 2: Is the path correct?** + +```bash +# macOS/Linux +test -d "$TEAM_ROOT/.squad" && echo "Valid" || echo "Invalid" + +# Windows +Test-Path "$env:TEAM_ROOT\.squad" +``` + +**Check 3: Are you using worktrees?** + +```bash +# macOS/Linux +git worktree list + +# Windows +git worktree list +``` + +If worktrees are used, ensure `worktree_path` is set in `.squad/team.md`. + +**Resolution:** Set TEAM_ROOT environment variable or update worktree_path config. + +--- + +### Problem: "Model unavailable" + +**Cause:** Primary model not available; fallback chain explanation. + +**Check:** Which models are configured? + +```bash +# macOS/Linux +grep -A 3 "models:" squad.config.ts + +# Windows +Select-String -Path "squad.config.ts" -Pattern "models:" -A 3 +``` + +**Resolution:** Squad falls back to: Primary model β†’ GPT-4 β†’ GPT-3.5-Turbo. Ensure at least one is available in your environment. + +--- + +## Nap Troubleshooting + +Squad nap is a **context hygiene system** that compresses agent histories, prunes old logs, archives decisions, and merges inbox files. It keeps `.squad/` lean across sessions. + +> **Trigger:** `squad nap` CLI command or `team, take a nap` in interactive shell. +> +> **Key point:** Simply closing the CLI does NOT perform napping. You must explicitly trigger it. + +--- + +### 5 Nap Operations + +| # | Operation | Trigger Condition | Action | +|---|-----------|-------------------|--------| +| 1 | **History compression** | Agent `history.md` > 15 KB | Keep 5 most recent sections, archive rest to `history-archive.md` | +| 2 | **Log pruning** | Log files > 7 days old | Delete old files from `.squad/orchestration-log/` and `.squad/log/` | +| 3 | **Decision archival** | `decisions.md` > 20 KB | Archive entries > 30 days old to `decisions-archive.md` | +| 4 | **Inbox cleanup** | Files exist in `decisions/inbox/` | Merge into `decisions.md`, delete source files | +| 5 | **Safety journal** | Always | Creates `.nap-journal` at start, deletes at end | + +--- + +### Nap Troubleshooting Flowchart + +#### Problem: "Nap says nothing to clean up" + +**Check 1: Are files under threshold?** + +```bash +# Check history sizes (macOS/Linux) +du -sh .squad/agents/*/history.md + +# Windows equivalent +Get-ChildItem -Path ".\.squad\agents\*\history.md" | ForEach-Object { "{0}: {1} bytes" -f $_.FullName, (Get-Item $_).Length } +``` + +**Threshold:** 15 KB β€” files under this are skipped. + +**Check 2: Are logs too new?** + +```bash +# Check log ages (macOS/Linux) +ls -la .squad/orchestration-log/ +ls -la .squad/log/ + +# Windows equivalent +Get-ChildItem -Path ".\.squad\orchestration-log", ".\.squad\log" -Force +``` + +**Logs < 7 days old are not pruned.** + +**Check 3: Is decisions.md small?** + +```bash +# Check file size (macOS/Linux) +wc -c .squad/decisions.md + +# Windows equivalent +(Get-Item .\.squad\decisions.md).Length +``` + +**Threshold:** 20 KB β€” under this, no archival. + +**Resolution:** This is normal behavior β€” nap only acts when thresholds are exceeded. Use `squad nap --deep` (keeps 3 entries instead of 5) for more aggressive cleanup, or wait for more sessions to accumulate data. + +--- + +#### Problem: "Nap appears to run but nothing changes" + +**Check 1: Verify `.squad/` directory exists and is writable** + +```bash +# macOS/Linux +ls -la .squad/ +touch .squad/test-write && rm .squad/test-write + +# Windows +Get-Item -Path ".\.squad" -Force +New-Item -Path ".\.squad\test-write.txt" -Force; Remove-Item -Path ".\.squad\test-write.txt" +``` + +**Check 2: Check if agent directories exist** + +```bash +# macOS/Linux +ls .squad/agents/ + +# Windows +Get-ChildItem -Path ".\.squad\agents" +``` + +Should show agent directories (e.g., `avery/`, `morgan/`, `quinn/`, etc.). + +**Check 3: Check for history files** + +```bash +# macOS/Linux +ls .squad/agents/*/history.md + +# Windows +Get-ChildItem -Path ".\.squad\agents\*\history.md" +``` + +If no history files exist, there's nothing to compress. + +**Check 4: Run dry-run to see what WOULD happen** + +```bash +squad nap --dry-run +``` + +**Resolution:** If agents have no `history.md` files, the team hasn't accumulated learnings yet. Run some tasks first, then nap. + +--- + +#### Problem: "Previous nap interrupted" warning + +**Cause:** A previous nap was interrupted (crash, Ctrl+C, terminal closed during nap). + +**Check:** + +```bash +# macOS/Linux +ls .squad/.nap-journal + +# Windows +Test-Path ".\.squad\.nap-journal" +``` + +If this file exists, a nap was interrupted. + +**Resolution:** Re-run `squad nap` β€” it will complete the interrupted operations and remove the journal file. The journal is a safety mechanism, not an error. + +--- + +#### Problem: "History file still large after nap" + +**Check 1: Is it actually over 15 KB?** + +```bash +# macOS/Linux +wc -c .squad/agents/avery/history.md + +# Windows +(Get-Item ".\.squad\agents\avery\history.md").Length +``` + +**Check 2: Was an archive file created?** + +```bash +# macOS/Linux +ls .squad/agents/avery/history-archive.md + +# Windows +Test-Path ".\.squad\agents\avery\history-archive.md" +``` + +Should exist after compression. + +**Check 3: Does the history have dated sections?** + +The compressor looks for markdown sections (`## Date` or `## Session`) to identify entry boundaries. If the history is one undated block, it can't split entries to archive. + +**Resolution:** If the file has no dated sections, the compressor can't identify individual entries. Ensure agents write structured history with dated headers. + +--- + +#### Problem: "Decisions not archiving" + +**Check 1: File size** + +```bash +# macOS/Linux +wc -c .squad/decisions.md + +# Windows +(Get-Item ".\.squad\decisions.md").Length +``` + +Must be > 20 KB for archival to trigger. + +**Check 2: Entry dates** + +Nap archives entries > 30 days old. If all entries are recent, nothing is archived even if the file is large. + +**Check 3: Undated entries** + +Undated entries (common for foundational directives like AD-001) are **never archived**. This is by design. + +**Resolution:** If the file is > 20 KB but all entries are < 30 days old, wait or manually archive old entries. + +--- + +#### Problem: "Inbox files not merging" + +**Check 1: Do inbox files exist?** + +```bash +# macOS/Linux +ls .squad/decisions/inbox/ + +# Windows +Get-ChildItem -Path ".\.squad\decisions\inbox" +``` + +**Check 2: Are they `.md` files?** + +Only markdown files are processed. Other file types are ignored. + +**Check 3: Check file permissions** + +```bash +# macOS/Linux +ls -la .squad/decisions/inbox/*.md + +# Windows +Get-ChildItem -Path ".\.squad\decisions\inbox\*.md" -Force +``` + +**Resolution:** Ensure inbox files are `.md` format and readable. + +--- + +#### Problem: "Session can't be recovered after nap" + +**Important:** Nap does NOT affect sessions. Sessions are a separate system. + +**Check session store:** + +```bash +# In Copilot CLI +sql database: "session_store" query: "SELECT id, summary, updated_at FROM sessions ORDER BY updated_at DESC LIMIT 5" +``` + +**Check session files:** + +```bash +# macOS/Linux +ls .squad/sessions/ + +# Windows +Get-ChildItem -Path ".\.squad\sessions" +``` + +JSON files with format: `{timestamp}_{sessionId}.json` + +**Sessions auto-expire after 24 hours.** If the session is older, it may have been cleaned up. + +--- + +## CI/CD Issues + +### Problem: "Tests fail in CI but pass locally" + +**Common causes:** + +1. **Missing build steps** β€” CI runs tests before build completes +2. **Environment differences** β€” CI doesn't have required Node.js version, dependencies, or env variables +3. **Git state** β€” CI checks out detached HEAD; Squad expects a branch +4. **SSH keys** β€” CI agent can't access private repos + +**Check 1: CI Node.js version** + +```bash +# In GitHub Actions workflow log, look for: +node --version +# Must be >= v20 +``` + +**Check 2: Dependencies installed?** + +```bash +# Workflow should include: +npm ci # or npm install +``` + +**Check 3: Is this a private repo?** + +If yes, ensure CI has GitHub token with repo scope: + +```yaml +# In workflow +env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +**Resolution:** Add build step before tests in your CI workflow. Ensure Node.js v20+ is used. + +--- + +### Problem: "PR checks blocked" + +**Cause:** Draft PR status, missing review, or failed CI. + +**Check 1: Is the PR draft?** + +```bash +gh pr view --json isDraft +``` + +If `isDraft: true`, convert to ready: + +```bash +gh pr ready +``` + +**Check 2: Does PR require reviews?** + +```bash +gh pr view --json reviewDecision +``` + +If reviews required, request them: + +```bash +gh pr review --request-review @{reviewer} +``` + +**Check 3: CI failures?** + +```bash +gh pr checks +``` + +If failed, fix the issues and push a new commit β€” CI will rerun. + +**Resolution:** Ensure PR is ready, has approvals, and all checks pass. + +--- + +### Problem: "Workflow runs stale code" + +**Cause:** CI runs the workflow from the base branch (main/dev), not the PR branch. + +**Example:** PR #42 on `feature` branch, but CI runs workflow.yml from `main`. + +**Check:** + +```bash +# View workflow source branch +git show origin/main:.github/workflows/ci.yml +git show origin/feature:.github/workflows/ci.yml +``` + +If they differ, CI ran the main version. + +**Resolution:** Either: + +1. Update the base branch workflow and push to base +2. Or configure workflow to always use the PR branch: + +```yaml +# In .github/workflows/ci.yml +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.head.sha }} +``` + +--- + +## Decisions & History Issues + +### Problem: "decisions.md is huge" + +**Cause:** Archival not running or threshold too high. + +**Check 1: File size** + +```bash +# macOS/Linux +wc -c .squad/decisions.md + +# Windows +(Get-Item ".\.squad\decisions.md").Length +``` + +**Check 2: Is nap running regularly?** + +```bash +# Check nap schedule (e.g., in your CI or shell workflow) +grep -r "squad nap" .squad/decisions/ +``` + +**Check 3: What's the archival threshold?** + +Default: 20 KB. If file is > 20 KB, run `squad nap` manually: + +```bash +squad nap +``` + +Or use aggressive mode: + +```bash +squad nap --deep +``` + +**Resolution:** Set up nap to run after each session (e.g., post-nap ritual in `.squad/team.md`). Or manually run `squad nap --deep` quarterly. + +--- + +### Problem: "Inbox files not merging" + +**Cause:** Scribe not running, or permission issues. + +**Check 1: Do inbox files exist?** + +```bash +# macOS/Linux +ls .squad/decisions/inbox/ + +# Windows +Get-ChildItem -Path ".\.squad\decisions\inbox" +``` + +**Check 2: Are they markdown files?** + +Only `.md` files are processed. If you have `.txt` or other extensions, rename them. + +**Check 3: Check file permissions** + +```bash +# macOS/Linux +ls -la .squad/decisions/inbox/*.md + +# Windows +Get-ChildItem -Path ".\.squad\decisions\inbox\*.md" -Force +``` + +**Check 4: Manually run nap to merge** + +```bash +squad nap --dry-run # preview +squad nap # execute +``` + +**Resolution:** Ensure files are `.md` format and readable. Run `squad nap` to merge. + +--- + +### Problem: "History lost after branch merge" + +**Cause:** Git merge didn't use the `union` merge driver. + +**Check:** Is `.gitattributes` correct? + +```bash +# macOS/Linux +cat .gitattributes | grep history + +# Windows +Get-Content ".\.gitattributes" | Select-String "history" +``` + +Should show: + +``` +.squad/agents/*/history.md merge=union +``` + +**If missing, add it:** + +```bash +echo ".squad/agents/*/history.md merge=union" >> .gitattributes +git add .gitattributes +git commit -m "fix: add union merge driver for history files" +``` + +**For future merges:** The union driver will auto-merge history without conflicts. + +**Resolution:** Add merge=union driver to .gitattributes and recommit merge. + +--- + +## Nap Variants Reference + +| Command | Keep Entries | When to Use | +|---------|-------------|-------------| +| `squad nap` | 5 recent | Regular maintenance (every 3-5 sessions) | +| `squad nap --deep` | 3 recent | Sprint end, milestone cleanup | +| `squad nap --dry-run` | N/A (preview) | Before first nap, or to diagnose issues | +| `/compact` (in shell) | 5 recent | Same as `squad nap` from REPL | + +--- + +## Key Thresholds + +| Metric | Default | Notes | +|--------|---------|-------| +| History compression | 15 KB | Per-agent `history.md` | +| Decision archival | 20 KB | `decisions.md` total size | +| Log max age | 7 days | Orchestration + session logs | +| Decision entry max age | 30 days | Before archival eligible | +| Token estimate | 250/KB | For reporting savings | + +--- + +## Quick Diagnostic Script + +```bash +#!/bin/bash +echo "=== Squad Nap Diagnostics ===" +echo "" +echo "History files:" +for f in .squad/agents/*/history.md; do + size=$(wc -c < "$f" 2>/dev/null || echo "0") + echo " $f: ${size} bytes $([ $size -gt 15360 ] && echo '[WILL COMPRESS]' || echo '[under threshold]')" +done +echo "" +echo "Decisions: $(wc -c < .squad/decisions.md 2>/dev/null || echo 0) bytes" +echo "Inbox files: $(ls .squad/decisions/inbox/*.md 2>/dev/null | wc -l)" +echo "Log files > 7d: $(find .squad/log .squad/orchestration-log -mtime +7 2>/dev/null | wc -l)" +echo "Nap journal: $([ -f .squad/.nap-journal ] && echo 'EXISTS (interrupted nap!)' || echo 'clean')" +``` + +**Windows PowerShell equivalent:** + +```powershell +Write-Host "=== Squad Nap Diagnostics ===" +Write-Host "" +Write-Host "History files:" +Get-ChildItem -Path ".\.squad\agents\*\history.md" -ErrorAction SilentlyContinue | ForEach-Object { + $size = (Get-Item $_).Length + $status = if ($size -gt 15360) { "[WILL COMPRESS]" } else { "[under threshold]" } + Write-Host " $($_.FullName): $size bytes $status" +} +Write-Host "" +$decisionsSize = if (Test-Path ".\.squad\decisions.md") { (Get-Item ".\.squad\decisions.md").Length } else { 0 } +Write-Host "Decisions: $decisionsSize bytes" +$inboxCount = @(Get-ChildItem -Path ".\.squad\decisions\inbox\*.md" -ErrorAction SilentlyContinue).Count +Write-Host "Inbox files: $inboxCount" +$sevenDaysAgo = (Get-Date).AddDays(-7) +$oldLogs = @(Get-ChildItem -Path ".\.squad\log", ".\.squad\orchestration-log" -ErrorAction SilentlyContinue | Where-Object { $_.LastWriteTime -lt $sevenDaysAgo }).Count +Write-Host "Log files > 7d: $oldLogs" +$journalExists = if (Test-Path ".\.squad\.nap-journal") { "EXISTS (interrupted nap!)" } else { "clean" } +Write-Host "Nap journal: $journalExists" +``` diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts index 76bfc212e..f32862735 100644 --- a/docs/src/navigation.ts +++ b/docs/src/navigation.ts @@ -118,7 +118,7 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'Client Compatibility', slug: 'scenarios/client-compatibility' }, { title: 'Remote Q&A', slug: 'scenarios/remote-qa' }, { title: 'Disaster Recovery', slug: 'scenarios/disaster-recovery' }, - { title: 'Troubleshooting', slug: 'scenarios/troubleshooting' }, + { title: 'Troubleshooting Guide', slug: 'scenarios/squad-troubleshooting' }, { title: 'Aspire Dashboard', slug: 'scenarios/aspire-dashboard' }, ], },