diff --git a/docs/skills/project-instructions-health/SKILL.md b/docs/skills/project-instructions-health/SKILL.md new file mode 100644 index 0000000..ad7e41d --- /dev/null +++ b/docs/skills/project-instructions-health/SKILL.md @@ -0,0 +1,225 @@ +--- +name: project-instructions-health +description: | + Validate Claude Project instructions against live infrastructure state. Use this skill whenever: + - Starting a new session and wanting to verify instructions are current + - After deploying infrastructure changes (new servers, new services, changed IPs) + - After adding or removing MCP connectors + - After changing subscription tiers, policies, or branding + - When a Chronicler suspects instructions reference something stale + - Periodically as preventive maintenance (every ~10 sessions) + This skill catches drift between what the project instructions say and what actually exists, preventing Chroniclers from operating on outdated assumptions. +--- + +# Project Instructions Health Checker + +Validates the Claude Project instructions against live Firefrost infrastructure. Catches stale references, missing capabilities, outdated IPs, wrong tier names, and other drift before it causes problems. + +--- + +## WHEN TO RUN + +- **Session start (optional):** Quick check after the Joining Protocol if you suspect instructions may be stale +- **After infrastructure changes:** Any time a server is added/removed/moved, an IP changes, a service is deployed or decommissioned, or an MCP connector is added/removed +- **After policy changes:** Tier pricing, branding updates, the "We Don't Kick People Out" policy, or any load-bearing policy documented in the instructions +- **On request:** When Michael says "check the instructions" or "are the instructions up to date" + +--- + +## HOW TO RUN + +Execute these checks in order. Each check is independent — a failure in one doesn't block the others. Collect all results and report at the end. + +### Check 1: Server Connectivity + +Verify every server listed in the instructions is reachable via Trinity Core. + +```bash +# Call Trinity Core:list_servers and compare against the Infrastructure table +# in the project instructions. Flag any server that: +# - Is listed in instructions but NOT in Trinity Core's roster +# - Is in Trinity Core's roster but NOT in the instructions +# - Has a different IP than what the instructions say +``` + +**How to verify IPs:** +```bash +# For each server in Trinity Core's roster: +Trinity Core:run_command(server="", command="hostname -I | awk '{print $1}'") +# Compare the returned IP against the instructions table +``` + +**Pass criteria:** All servers in instructions match Trinity Core roster AND IPs match. + +### Check 2: MCP Connectors + +Verify the connectors listed in the instructions match what's actually available. + +```bash +# Call tool_search with queries for each listed connector: +# "Canva", "Cloudflare", "Stripe", "Google Calendar", "Gmail", "Mermaid Chart", "Trinity Core" +# Flag any connector that: +# - Is listed in instructions but fails to load +# - Is available but NOT listed in instructions +``` + +**Pass criteria:** Every listed connector loads, no unlisted connectors discovered. + +### Check 3: Gitea Repos + +Verify the repos listed in the instructions exist and the listed branches are correct. + +```bash +# For each repo in the Repo Reference table: +curl -s -H "Authorization: token " \ + "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming//branches" \ + | python3 -c "import sys,json; [print(b['name']) for b in json.load(sys.stdin)]" +# Flag if the default branch doesn't match what the instructions say +``` + +**Pass criteria:** All repos exist, default branches match. + +### Check 4: Arbiter Health + +Verify Arbiter is running and the documented endpoints respond. + +```bash +Trinity Core:run_command(server="command-center", command="systemctl is-active arbiter-3") +Trinity Core:run_command(server="command-center", command="curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3500/admin/") +``` + +**Pass criteria:** Service active, admin endpoint returns 200 or 302 (redirect to login). + +### Check 5: Database Access + +Verify the documented database credentials work. + +```bash +Trinity Core:run_command(server="command-center", command="PGPASSWORD='FireFrost2026!Arbiter' psql -U arbiter -h 127.0.0.1 -d arbiter_db -c 'SELECT 1'") +``` + +**Pass criteria:** Query returns `1` without error. + +### Check 6: Subscription Tiers + +Verify the tiers listed in the instructions match what's configured in Arbiter. + +```bash +Trinity Core:run_command(server="command-center", command="PGPASSWORD='FireFrost2026!Arbiter' psql -U arbiter -h 127.0.0.1 -d arbiter_db -tAc \"SELECT DISTINCT tier_level FROM subscriptions ORDER BY tier_level;\"") +``` + +Also check `src/routes/admin/constants.js` in the services repo for the TIER_INFO definition: +```bash +grep -A 30 "TIER_INFO" /home/claude/firefrost-services/services/arbiter-3.0/src/routes/admin/constants.js +``` + +**Pass criteria:** Tiers in the database and constants file match the instructions table. The top tier is SOVEREIGN (never "Founder"). + +### Check 7: Website Deploy Pipeline + +Verify the website auto-deploy mechanism is intact. + +```bash +# Check that the website repo's main branch exists and has recent activity: +curl -s -H "Authorization: token " \ + "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-website/branches/main" \ + | python3 -c "import sys,json; d=json.load(sys.stdin); print('last commit:', d['commit']['message'][:80])" + +# Verify the live site responds: +curl -s -o /dev/null -w "%{http_code}" https://firefrostgaming.com/ +``` + +**Pass criteria:** Repo branch exists, live site returns 200. + +### Check 8: Policy Page + +Verify the "We Don't Kick People Out" policy page is live and contains the expected content markers. + +```bash +curl -s https://firefrostgaming.com/cancellation-refund/ | grep -c "Awakened\|appealForm\|We Don't Kick" +``` + +**Pass criteria:** At least 2 of the 3 markers found (confirms page is live and has the right content). + +### Check 9: Clone Size + +Verify the ops manual clone size is still healthy (post-Task #101 cleanup). + +```bash +# After the standard session-start clone: +du -sh /home/claude/firefrost-operations-manual/.git +``` + +**Pass criteria:** Under 150 MB. If over 300 MB, large binary files may have been re-committed — investigate with: +```bash +git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectsize) %(rest)' | awk '$1=="blob" && $2>1000000' | sort -k2 -rn | head -10 +``` + +### Check 10: Stale References + +Scan the instructions text for references to things that no longer exist. + +```bash +# Check for references to decommissioned services: +# - Ghost CMS (decommissioned April 2-3, 2026) +# - Paymenter (decommissioned April 2-3, 2026) +# - SSH blocked (no longer true since Trinity Core) +# - "Founder" tier (correct name is SOVEREIGN) +# - sparse checkout (no longer needed since Task #101) +``` + +**How:** Read through the project instructions in context and flag any mention of: +- `Ghost` or `ghost` (unless clearly historical) +- `Paymenter` or `paymenter` (unless clearly historical) +- `SSH is blocked` or `SSH.*cannot` or `port 22.*blocked` +- `Founder` as a tier name (should be `Sovereign`) +- `sparse checkout` as a recommendation (should say full clone) + +**Pass criteria:** Zero stale references found. + +--- + +## REPORTING FORMAT + +After running all checks, report like this: + +``` +📋 Project Instructions Health Check — [Date] + +✅ Check 1: Server Connectivity — PASS (7/7 servers reachable, IPs match) +✅ Check 2: MCP Connectors — PASS (7/7 connectors load) +⚠️ Check 3: Gitea Repos — WARNING (firefrost-staff-wiki not in instructions but exists) +✅ Check 4: Arbiter Health — PASS (active, admin returns 302) +✅ Check 5: Database Access — PASS +✅ Check 6: Subscription Tiers — PASS (6 tiers, top = Sovereign) +✅ Check 7: Website Deploy — PASS (main branch active, site returns 200) +✅ Check 8: Policy Page — PASS (3/3 markers found) +✅ Check 9: Clone Size — PASS (62 MB) +✅ Check 10: Stale References — PASS (0 found) + +Result: 9/10 PASS, 1 WARNING +Action needed: Add firefrost-staff-wiki to Repo Reference table +``` + +Use ✅ for PASS, ⚠️ for WARNING (non-critical drift), ❌ for FAIL (instructions are actively wrong about something load-bearing). + +--- + +## AFTER THE CHECK + +- If all checks pass: note it in the session log and move on. +- If warnings found: mention them to Michael, suggest the fix, apply if he approves. +- If failures found: **stop and fix before doing other work.** A Chronicler operating with wrong instructions is worse than a Chronicler operating with no instructions. Fix the instructions text, generate the updated file, and have Michael paste it into the Project config. + +--- + +## MAINTAINING THIS SKILL + +When new infrastructure is added (servers, connectors, services, repos), add a corresponding check to this skill. The skill should grow alongside the infrastructure it validates. + +When checks become obsolete (e.g., a service is permanently decommissioned and removed from instructions), remove the corresponding check so the skill doesn't accumulate dead weight. + +--- + +*Created by Chronicler #81 — April 11, 2026* +*"Trust but verify. Then verify the verifier."*