| 1 | # SquadScope Rollout Checklist |
| 2 | |
| 3 | Use this checklist to verify your SquadScope instance is ready for production. Complete each item before considering the system operational. |
| 4 | |
| 5 | ## Pre-Launch |
| 6 | |
| 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.161.1 to match CI) |
| 11 | |
| 12 | - [ ] **Copilot auth configured** |
| 13 | - [ ] Fine-grained PAT created with **Account → Copilot Requests** permission |
| 14 | - [ ] Token is `github_pat_...` (not `ghp_...`) |
| 15 | - [ ] Secret `COPILOT_GH_TOKEN` set in repo: `gh secret set COPILOT_GH_TOKEN --body TOKEN -R OWNER/REPO` |
| 16 | - [ ] Secret verified: `gh secret list -R OWNER/REPO` shows `COPILOT_GH_TOKEN` |
| 17 | - [ ] (Optional) Copilot subscription verified at https://github.com/settings/copilot |
| 18 | |
| 19 | - [ ] **GitHub Pages enabled** |
| 20 | - [ ] Repo **Settings → Pages → Source** set to "GitHub Actions" |
| 21 | - [ ] No errors in Pages deployment section |
| 22 | |
| 23 | ## First-Time Testing |
| 24 | |
| 25 | - [ ] **Local build succeeds** |
| 26 | - [ ] Run `hugo server` locally and verify site loads at http://localhost:1313 |
| 27 | - [ ] No Hugo build errors in console |
| 28 | - [ ] Run `hugo --minify` and verify `public/` directory created with HTML files |
| 29 | - [ ] Run `npx pagefind --site public/` and verify `public/pagefind/pagefind-ui.js` exists |
| 30 | |
| 31 | - [ ] **First manual crawl successful** |
| 32 | - [ ] Trigger: `gh workflow run crawl-and-publish.yml -R OWNER/REPO` |
| 33 | - [ ] Monitor: `gh run list -R OWNER/REPO --workflow crawl-and-publish.yml` |
| 34 | - [ ] Verify: Green checkmark in Actions tab |
| 35 | - [ ] Artifacts created: `data/raw/YYYY-WNN.json` and `data/snapshots/YYYY-WNN-stars.json` |
| 36 | |
| 37 | - [ ] **First manual analysis successful** |
| 38 | - [ ] Previous crawl completed |
| 39 | - [ ] Verify: `data/analyzed/YYYY-WNN-summary.md` exists and contains valid Markdown + YAML |
| 40 | - [ ] Check: YAML frontmatter includes `quality_score`, `title`, `date`, `categories` |
| 41 | - [ ] Check: File contains `## This Week's Trends`, `## Where Industry Meets Code`, `## Signal & Noise`, `## Blind Spots`, `## The Week Ahead`, `## Key References` |
| 42 | |
| 43 | - [ ] **Quality gate passed** |
| 44 | - [ ] Analysis quality_score ≥ 60 (check frontmatter) |
| 45 | - [ ] Gate did NOT block publish (workflow continued to deploy step) |
| 46 | - [ ] Content sections present and not empty |
| 47 | |
| 48 | - [ ] **Site deploys correctly** |
| 49 | - [ ] Wait for full workflow to complete (crawl + analyze + generate + deploy) |
| 50 | - [ ] Monitor: **Actions → Crawl and Publish → Latest run → Deploy Pages** shows success |
| 51 | - [ ] Verify: GitHub Pages shows "Deployment successful" |
| 52 | - [ ] Verify: deployed search still works and the build includes fresh `pagefind/` assets |
| 53 | |
| 54 | - [ ] **RSS feed accessible** |
| 55 | - [ ] Visit: `https://PAGES_URL/index.xml` (replace with your Pages domain) |
| 56 | - [ ] Verify: Valid XML returned (not 404 or error) |
| 57 | - [ ] Verify: Latest week's summary appears in feed items |
| 58 | |
| 59 | - [ ] **Content visible on site** |
| 60 | - [ ] Visit: `https://PAGES_URL/` (your GitHub Pages site) |
| 61 | - [ ] Verify: Site loads without errors |
| 62 | - [ ] Verify: Latest week appears in post list |
| 63 | - [ ] Click into latest week's article and verify content renders correctly |
| 64 | |
| 65 | ## Pre-Production |
| 66 | |
| 67 | - [ ] **Cron schedule enabled** |
| 68 | - [ ] Verify workflow file: `.github/workflows/crawl-and-publish.yml` has schedule trigger: |
| 69 | ```yaml |
| 70 | schedule: |
| 71 | - cron: '53 11 * * 0' # Sunday 11:53 UTC |
| 72 | ``` |
| 73 | - [ ] Confirm schedule is correct for your timezone |
| 74 | - [ ] Confirm operators understand GitHub-hosted `schedule` is best-effort and may start hours late on shared runners |
| 75 | - [ ] If punctual launches matter, document who owns the external scheduler or manual `gh workflow run crawl-and-publish.yml -R OWNER/REPO` fallback |
| 76 | |
| 77 | - [ ] **Run counter initialized** |
| 78 | - [ ] File exists: `.squad/run-counter.txt` |
| 79 | - [ ] Contains integer counter (e.g., `1`) |
| 80 | - [ ] Reskill only triggers on positive multiples of 5 (`5`, `10`, `15`, ...), not when the counter is `0` |
| 81 | |
| 82 | ## First Automated Run |
| 83 | |
| 84 | - [ ] **Automated run completed (wait until the next Sunday schedule window or use a manual trigger)** |
| 85 | - [ ] Check the Actions tab after the schedule window; do not assume the run starts exactly at 11:53 UTC |
| 86 | - [ ] Verify workflow completed with green checkmark |
| 87 | - [ ] Monitor logs for any warnings or errors |
| 88 | |
| 89 | - [ ] **Data artifacts generated** |
| 90 | - [ ] `data/raw/YYYY-WNN.json` created (current week) |
| 91 | - [ ] `data/analyzed/YYYY-WNN-summary.md` created |
| 92 | - [ ] `content/weekly/YYYY/WNN.md` created |
| 93 | |
| 94 | - [ ] **Pages deployment succeeded** |
| 95 | - [ ] Pages Shows "Deployment successful" in deployment history |
| 96 | - [ ] Site updated with new week's content |
| 97 | |
| 98 | - [ ] **RSS feed updated** |
| 99 | - [ ] `https://PAGES_URL/index.xml` now shows the latest entry |
| 100 | - [ ] Feed readers can subscribe and receive new entries |
| 101 | |
| 102 | ## Post-Launch Monitoring |
| 103 | |
| 104 | - [ ] **Weekly runs continue automatically** |
| 105 | - [ ] Check Actions every Sunday/Monday window to confirm the workflow eventually ran |
| 106 | - [ ] (Optional) Set a calendar reminder to check after the scheduled window rather than at an exact minute |
| 107 | |
| 108 | - [ ] **Quality remains consistent** |
| 109 | - [ ] Review a few published analyses for quality |
| 110 | - [ ] If quality degrades, check workflow logs and Copilot API status |
| 111 | |
| 112 | - [ ] **Site remains accessible** |
| 113 | - [ ] Periodically visit your SquadScope site |
| 114 | - [ ] Verify RSS feed is updated each week |
| 115 | |
| 116 | ## Optional Verification |
| 117 | |
| 118 | - [ ] **Manual stage execution (debug only)** |
| 119 | - [ ] Crawl: `python3 scripts/crawl.py --as-of 2026-05-18` |
| 120 | - [ ] Analyze (local debug only — not a production fallback): `python3 scripts/analyze_fallback.py --raw-json data/raw/YYYY-WNN.json --output ./scratch-analysis.md --current-datetime 2026-05-18T16:00:00Z` |
| 121 | - [ ] Gate: `python3 scripts/analysis_gate.py --analysis-file data/analyzed/YYYY-WNN-summary.md --raw-json data/raw/YYYY-WNN.json --current-datetime 2026-05-18T16:00:00Z` |
| 122 | - [ ] Generate: `python3 scripts/generate_content.py data/analyzed/YYYY-WNN-summary.md` |
| 123 | - [ ] Build search assets after Hugo: `npx pagefind --site public/` |
| 124 | |
| 125 | - [ ] **Copilot auth failure handling (fail-closed verification)** |
| 126 | - [ ] Comment out or rename `COPILOT_GH_TOKEN` secret temporarily |
| 127 | - [ ] Manually trigger workflow |
| 128 | - [ ] Verify workflow fails cleanly with a clear error (no fallback — pipeline is Copilot-only, fail-closed) |
| 129 | - [ ] Confirm token-renewal issue automation triggers if configured |
| 130 | - [ ] Restore secret after testing |
| 131 | |
| 132 | - [ ] **Reskill cycle verified (after 5 runs)** |
| 133 | - [ ] Count automated runs (every scheduled weekly publish = 1 run) |
| 134 | - [ ] After 5 weeks, check for `.squad/reskill/YYYY-WNN.md` file |
| 135 | - [ ] Verify the workflow invokes the real reskill path (`scripts/reskill.py`) and outputs analysis + recommendations |
| 136 | |
| 137 | ## Sign-Off |
| 138 | |
| 139 | - **Operator name:** _______________ |
| 140 | - **Date:** _______________ |
| 141 | - **SquadScope instance:** https://_______________ |
| 142 | - **All items checked:** Yes ☐ / No ☐ |
| 143 | |
| 144 | **Notes:** |
| 145 | ``` |
| 146 | [Space for operator notes or issues encountered] |
| 147 | |
| 148 | |
| 149 | |
| 150 | |
| 151 | ``` |
| 152 | |
| 153 | --- |
| 154 | |
| 155 | ## Troubleshooting During Rollout |
| 156 | |
| 157 | If any checklist item fails, see `docs/operator-guide.md` for troubleshooting guidance: |
| 158 | |
| 159 | - **Auth failures:** Section "Copilot auth failure" |
| 160 | - **Rate limits:** Section "GitHub API rate limits exceeded" |
| 161 | - **Build failures:** Section "Hugo build fails" |
| 162 | - **Quality gate blocks:** Section "Quality gate blocks publish" |
| 163 | - **Pages doesn't update:** Section "GitHub Pages doesn't update" |
| 164 | - **Reskill doesn't trigger:** Section "Reskill workflow doesn't trigger" |
| 165 | |
| 166 | Good luck with your SquadScope rollout! 🚀 |