@cryptotaxi247 / SquadScope / commits / e8ccf63

Write operator docs and rollout checklist for SquadScope (#46)

* Fix deploy: remove .worktrees and add to .gitignore Remove the .worktrees/bender-pr32 directory from git tracking that was accidentally committed. Add .worktrees/ to .gitignore to prevent similar issues in the future. Also remove 'submodules: recursive' from the deploy-site.yml workflow since the project does not use git submodules. This was causing the 'fatal: No url found for submodule path' error during checkout. Fixes the Deploy Hugo site workflow failure. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Write operator docs and rollout checklist - Update README.md with complete project overview, architecture diagram, and quick start - Add What SquadScope is/does section with clear value proposition - Document 5-stage pipeline: Crawl → Analyze → Generate → Deploy → Reskill - Create docs/operator-guide.md with: - Prerequisites and initial setup (Copilot token, GitHub Pages, Hugo) - Step-by-step configuration guide - Manual workflow triggers and stage-by-stage execution - Complete troubleshooting section for common failures: - Copilot auth/quota issues - GitHub API rate limits - Hugo build failures - Quality gate blocks - Pages deployment issues - Reskill cycle explanation - Monitoring and health check procedures - Create docs/rollout-checklist.md with: - Pre-launch verification items - First-time testing checklist - Pre-production setup - First automated run validation - Post-launch monitoring - Sign-off section for operators Closes #23 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address all 8 Copilot review comments on operator docs (#46) - Fixed: Add submodules: recursive to deploy workflow checkout - Fixed: Correct RSS feed URL from /feed/ to /index.xml throughout docs - Fixed: Clarify raw crawl payload is JSON object, not array - Fixed: Align reskill description with current implementation - Fixed: Update quality gate verification language - Fixed: Replace squad-heartbeat workflow ref with reskill.py script Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <copilot@github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Juan Manuel Servera committed May 18, 2026 at 16:36 UTC e8ccf639ff76027b7abf0eb521d424a752ed7e5c

4 files changed +30 -21

.github/workflows/deploy-site.yml

@@ -26,6 +26,7 @@ jobs:

26 uses: actions/checkout@v4

27 with:

28 fetch-depth: 0

29 + submodules: recursive

31 - name: Configure GitHub Pages

32 uses: actions/configure-pages@v5

README.md

+6 -6

@@ -40,12 +40,12 @@ JSON Markdown Hugo Pages Improvements

41 **Stage 4: Deploy** (Hugo + GitHub Pages)

42 - Builds static site from Hugo and publishes to GitHub Pages

43 -- Outputs: Live website + RSS feeds at `https://your-site/feed/`

43 +- Outputs: Live website + RSS feeds at `https://your-site/index.xml` and `https://your-site/feed/`

45 **Stage 5: Reskill** (every 5th run)

46 -- Copilot reads squad history and decisions

47 -- Writes improvement recommendations to `.squad/reskill/YYYY-WNN.md`

48 -- Optional: Can trigger PR with proposed prompt refinements

46 +- Every 5th run, Copilot reviews squad history and recent analysis outputs

47 +- Writes observations and improvement recommendations to `.squad/reskill/YYYY-WNN.md`

48 +- Optional: Can trigger PR with proposed prompt refinements (not auto-merged)

50 ## Theme and stack

@@ -62,7 +62,7 @@ JSON Markdown Hugo Pages Improvements

62 ### For end users

64 1. **Visit the site:** [SquadScope](https://your-repo/): Browse weekly, monthly, yearly summaries

65 -2. **Subscribe to RSS:** Add `https://your-site/feed/` to your reader

65 +2. **Subscribe to RSS:** Add `https://your-site/index.xml` or `https://your-site/feed/` to your reader

66 3. **Check GitHub Releases:** New summaries also posted as releases

68 ### For operators (see `docs/operator-guide.md` for full setup)

@@ -91,7 +91,7 @@ JSON Markdown Hugo Pages Improvements

91 - `content/weekly/YYYY/WNN.md` — immutable weekly summaries (published once, never modified)

92 - `content/monthly/YYYY/MM.md` — monthly rollups (append-only)

93 - `content/yearly/YYYY.md` — yearly summaries (append-only)

94 -- `data/raw/YYYY-WNN.json` — crawler output (array of repo objects)

94 +- `data/raw/YYYY-WNN.json` — crawler output (JSON object with keys: `week`, `new_repos`, `trending_repos`, `signals`, `metadata`)

95 - `data/analyzed/YYYY-WNN-summary.md` — AI analysis with quality score

96 - `data/snapshots/YYYY-WNN-stars.json` — star count snapshots for trending analysis

docs/operator-guide.md

+20 -13

@@ -22,10 +22,15 @@ Before starting, ensure you have:

22 ### Step 1: Clone the repository

24 ```bash

25 -git clone https://github.com/YOUR_USERNAME/SquadScope.git

25 +git clone --recurse-submodules https://github.com/YOUR_USERNAME/SquadScope.git

26 cd SquadScope

27 ```

29 +If you forgot `--recurse-submodules`, initialize them now:

30 +

31 +```bash

32 +git submodule update --init --recursive

33 +```

34 ### Step 2: Verify Hugo version locally

36 Ensure your Hugo binary is v0.146.0 or newer:

@@ -129,25 +134,25 @@ For debugging or testing, run stages separately:

134 python3 scripts/crawl.py --as-of 2026-05-18

135 ```

136

132 -Output: `data/raw/2026-W21.json`, `data/snapshots/2026-W21-stars.json`

137 +Output: `data/raw/2026-W20.json`, `data/snapshots/2026-W20-stars.json`

138

139 #### Analyze (Fallback — if Copilot unavailable)

140

141 ```bash

142 python3 scripts/analyze_fallback.py \

138 - --raw-json data/raw/2026-W21.json \

139 - --output data/analyzed/2026-W21-summary.md \

143 + --raw-json data/raw/2026-W20.json \

144 + --output data/analyzed/2026-W20-summary.md \

145 --current-datetime 2026-05-18T16:00:00Z

146 ```

147

143 -Output: `data/analyzed/2026-W21-summary.md`

148 +Output: `data/analyzed/2026-W20-summary.md`

149

150 #### Quality gate

151

152 ```bash

153 python3 scripts/analysis_gate.py \

149 - --analysis-file data/analyzed/2026-W21-summary.md \

150 - --raw-json data/raw/2026-W21.json \

154 + --analysis-file data/analyzed/2026-W20-summary.md \

155 + --raw-json data/raw/2026-W20.json \

156 --current-datetime 2026-05-18T16:00:00Z

157 ```

158

@@ -156,10 +161,10 @@ If the gate fails, it will exit with a non-zero code and log the reason (e.g., q

161 #### Generate

162

163 ```bash

159 -python3 scripts/generate_content.py data/analyzed/2026-W21-summary.md

164 +python3 scripts/generate_content.py data/analyzed/2026-W20-summary.md

165 ```

166

162 -Output: `content/weekly/2026/W21.md`

167 +Output: `content/weekly/2026/W20.md`

168

169 #### Build and deploy

170

@@ -242,12 +247,14 @@ Navigate to **Actions → Crawl and Publish** in your repo. Green checkmarks = s

247

248 **Cause:**

249 - Hugo version mismatch (too old)

250 +- Theme submodules not initialized

251 - Corrupted frontmatter in generated content

252

253 **Fix:**

254 1. Check Hugo version: `hugo version` (must be v0.146.0+)

249 -2. Check generated markdown in `content/weekly/` for valid YAML frontmatter

250 -3. Run locally: `hugo server` to see detailed error messages

255 +2. Verify submodules: `git submodule update --init --recursive`

256 +3. Check generated markdown in `content/weekly/` for valid YAML frontmatter

257 +4. Run locally: `hugo server` to see detailed error messages

258

259 ### ❌ GitHub Pages doesn't update

260

@@ -288,7 +295,7 @@ Navigate to **Actions → Crawl and Publish** in your repo. Green checkmarks = s

295 **Fix:**

296 1. Run the workflow 4 more times to trigger a reskill (or wait for 4 more weeks)

297 2. Check `.squad/run-counter.txt` to see how many runs have executed

291 -3. To manually test reskill logic, run: `gh workflow run squad-heartbeat.yml -R YOUR_USERNAME/SquadScope` (separate workflow)

298 +3. To manually test reskill logic, run: `python3 scripts/reskill.py --current-week YYYY-WNN --current-datetime 2026-05-18T16:00:00Z` (or wait for automatic 5th run trigger in `crawl-and-publish.yml`)

299

300 ## The Reskill Cycle

301

@@ -362,7 +369,7 @@ MIN_WORD_COUNT = 200

369 ### Check RSS feed generation

370

371 ```bash

365 -curl https://YOUR_SITE/feed/

372 +curl https://YOUR_SITE/index.xml

373 ```

374

375 Should return valid XML with recent article entries.

docs/rollout-checklist.md

+3 -2

@@ -6,6 +6,7 @@ Use this checklist to verify your SquadScope instance is ready for production. C

7 - [ ] **Repository created**

8 - [ ] GitHub repository exists and is accessible

9 + - [ ] Submodules initialized: `git submodule update --init --recursive`

10 - [ ] Hugo version verified: `hugo version` (must be v0.146.0+)

12 - [ ] **Copilot auth configured**

@@ -40,7 +41,7 @@ Use this checklist to verify your SquadScope instance is ready for production. C

42 - [ ] **Quality gate passed**

43 - [ ] Analysis quality_score ≥ 60 (check frontmatter)

43 - - [ ] Gate did NOT block publish (no quality-gate-failure issue opened)

44 + - [ ] Gate did NOT block publish (workflow continued to deploy step)

45 - [ ] Content sections present and not empty

47 - [ ] **Site deploys correctly**

@@ -49,7 +50,7 @@ Use this checklist to verify your SquadScope instance is ready for production. C

50 - [ ] Verify: GitHub Pages shows "Deployment successful"

52 - [ ] **RSS feed accessible**

52 - - [ ] Visit: `https://PAGES_URL/feed/` (replace with your Pages domain)

53 + - [ ] Visit: `https://PAGES_URL/index.xml` (replace with your Pages domain)

54 - [ ] Verify: Valid XML returned (not 404 or error)

55 - [ ] Verify: Latest week's summary appears in feed items