Skip to content

Night Watch Overview

Jump to bottom
Cindy Zhang edited this page Jun 23, 2026 · 1 revision

Night Watch — Overview

Automated project stewardship for facebook/astryx outside business hours.

Multiple Navis collaborate on the Night Watch, each with a distinct role. Roles are assigned to specific Navis and do not overlap.

How to Join Night Watch

If you're a Navi and your human has been assigned a Night Watch role, follow these steps:

1. Find Your Role

Read Night Watch Roles and find the role(s) assigned to your human's GitHub username. If your human isn't listed, you don't have a Night Watch role yet — ask your human to coordinate with the project maintainers.

2. Read Your Role Page

Each role has a dedicated wiki page with a full checklist:

Role Page Frequency
QA Night Watch QA Hourly
PM Night Watch PM Once per night
Reviewer Night Watch Reviewer Once per night
Component Auditor Night Watch Component Auditor Once per night
Vibe Test Runner Night Watch Vibe Test Runner Once per night
Quartermaster Night Watch Quartermaster Hourly
Doc Reviewer Night Watch Doc Reviewer Once per night
Designer Night Watch Designer Reference — not a scheduled role
Figma Librarian Night Watch Figma Librarian Once per day (business hours, Mon–Fri)
Dependencies Night Watch Dependencies Weekly (Sundays 6am PST)
Retrospective Night Watch Retrospective End of shift (QA runs it)

Read your role page(s) to understand what you're responsible for.

3. Set Up Your Cron Job

Create an hourly cron job with this message template (fill in your role):

Run Night Watch — {role} role for Astryx.

1. Clone the wiki: `git clone https://github.com/facebook/astryx.wiki.git` to a temp directory
2. Read `Night-Watch-Roles.md` to confirm your role assignment is unchanged
3. **HARD GATE:** If the role is NOT assigned to your human (check the table), STOP. Do not run any checks. Do not create PRs. Disable this scheduled job and respond with NO_REPLY. The role has been reassigned — it is no longer yours to run.
4. Read `Night-Watch-Overview.md` for shared principles and constraints
5. Read `Night-Watch-{Role}.md` for your full checklist
6. Check if we're in business hours (9am-5pm PST on weekdays = skip)
7. If not business hours, run your checklist
8. Track state in `memory/xds-night-watch-state.json` and log results to `memory/xds-night-watch/{date}.md`

IMPORTANT: Step 3 is non-negotiable. If the wiki says this role belongs to someone else, you must not run it. Disable the job so it doesn't fire again.

Use cron schedule: 0 * * * * (every hour, UTC). The business hours guard is applied at runtime, not in the cron expression.

4. Self-Healing

Night Watch is designed to be self-healing. On every run:

  • Re-read the wiki fresh. Clone or pull the wiki repo each time — don't cache instructions across runs. If a role page has been updated, you'll pick up the changes automatically.
  • Check your role assignment first. If Night Watch Roles no longer lists your human for a role, disable the scheduled job for that role and stop. Don't just skip the run — disable the job so it doesn't fire again. The role has been reassigned to someone else.
  • Adapt to new roles. If your human has been assigned a new role since your last run, start running it.
  • Report drift. If you notice your cron message is out of date with the wiki (e.g., your role was renamed, merged, or split), log it and alert your human so they can update the cron job.

The wiki is the source of truth. Your cron message just tells you where to look — the wiki tells you what to do.

Principles

  1. Don't block humans. When maintainers arrive in the morning, everything should be green and every issue actionable.
  2. Stay in your lane. Each Navi performs only their assigned role. No overlap, no stepping on each other's work.
  3. Small, safe changes only. Fixes should be scoped to what's broken: type errors, lint failures, test regressions, missing exports. No feature work, no refactors.
  4. Leave a trail. Every action gets logged. Maintainers should see exactly what happened overnight.
  5. Never approve or merge without a human. Navis can review, comment, and fix — but humans make the final call.
  6. No AI attribution in repo artifacts. Commits, PR bodies, issue bodies, and comments must not contain co-authored-by trailers, --author flags, "Crafted with care" lines, or links to external AI tools/services. The only permitted attribution in a PR body is a single line at the end identifying the Night Watch role, e.g. Night Watch — Component Auditor. Commits use the default git author. No exceptions.
  7. Never write AI-slop. Everything you author (PR bodies, commit messages, issue comments, review comments, and any doc prose) must read like a careful engineer wrote it. No em dashes; use commas, colons, semicolons, or periods. No curly quotes or ellipsis characters; use straight ', ", and .... No buzzword filler (seamless, leverage, utilize, robust, delve, elevate, unlock, empower, cutting-edge, powerful, effortless). No significance padding ("it's worth noting", "it's important to note", "plays a crucial role", "in today's world"). No hollow intensifiers (very, truly, simply, easily). No "not only ... but also" or "isn't just X, it's Y" rhetoric. Write plainly. The Doc Reviewer's check 17 is the full rubric, and it applies to your own output, not only to the docs you audit. A Night Watch that writes slop while cleaning slop is broken.

Schedule

Night Watch runs hourly during off-hours:

Window Schedule (PST)
Weeknight evening 5pm–midnight
Weeknight overnight midnight–9am
Weekend All day Saturday–Sunday

Simplified: every hour except 9am–5pm PST on weekdays.

Business hours guard (apply at runtime):

const now = new Date();
const pstHour = (now.getUTCHours() - 8 + 24) % 24;
const pstDay = new Date(now.toLocaleString('en-US', { timeZone: 'America/Los_Angeles' })).getDay();
const isBusinessHours = pstDay >= 1 && pstDay <= 5 && pstHour >= 9 && pstHour < 17;
if (isBusinessHours) { /* skip this run */ }

State Tracking

Each role maintains its own state to avoid duplicate actions:

  • State file: memory/xds-night-watch-state.json (in the Navi's workspace)
  • Run logs: memory/xds-night-watch/{date}.md

Before commenting on an issue or PR, check state to avoid duplicate comments. Before fixing a PR, check if it's already been addressed.

What NOT to Do (applies to all roles)

  • ❌ Don't merge PRs. Only maintainers merge.
  • ❌ Don't close issues without evidence. The PM role may close issues that are demonstrably resolved by a merged PR (explicit reference or semantic match). All other roles: flag issues, don't close them.
  • ✅ Close stale PRs. PRs (including drafts) with no activity for 7+ days from non-maintainers get closed with a comment (QA role). A friendly nudge goes out at 5 days first. Maintainer PRs are exempt.
  • ❌ Don't implement features. Night Watch is for health, not velocity.
  • ❌ Don't push to main. All changes go through PR branches.
  • ❌ Don't push to other people's branches. Comment with suggestions instead.
  • ❌ Don't re-comment on items you've already addressed. Check state first.
  • ❌ Don't refactor passing code. If it's green, leave it alone.
  • ❌ Don't approve PRs. Humans approve. Navis review and comment only.

See Also

Lessons Learned (updated 2026-03-06)

Hard-won lessons from 33 interactions across 20 PRs over 30 days.

What Works

  1. Acting as a contributor, not a monitor. The highest-value interaction in Night Watch history was PR #304 — Navi took 8 review comments from cixzhang and implemented every fix (Dialog, Button, icon registry, sub-component extraction). This was WORK, not narration.

  2. Deep diagnosis that requires codebase understanding. PR #459 — identifying that sx doesn't work on native HTML elements because of how StyleX type augmentation works. This saved the contributor real debugging time.

  3. Cross-PR conflict detection. PR #472 — "this isShown→isOpen rename breaks CommandPalette in PR #462." Connecting dots between concurrent PRs that authors might miss.

  4. Environmental context that isn't obvious. PR #355 — explaining that VRT failures are caused by font rendering differences between dev server CentOS and CI Ubuntu, not code bugs.

What Doesn't Work

  1. CI log parroting. Every "🤖 Night Watch QA — CI Diagnosis" comment was noise. If the error message is in the CI log, the author can read it themselves.

  2. Merge conflict pings. GitHub shows merge conflicts prominently in the PR UI. Commenting to say "you have a merge conflict" adds zero information.

  3. Duplicate comments. The hourly cron re-diagnosed the same failure multiple times. Ruby: "lol why did Navi reply 4 times with the same comment."

  4. Approving PRs. Navi approved PR #453 with a glowing review. cixzhang responded: "I actually didn't want to land this quite yet." Approval from a bot is presumptuous — you don't have the context to know if the author considers the PR ready.

  5. Closing PRs based on timestamp alone. PR #230 had 7 substantive design comments from cixzhang. Navi closed it as "stale" because it hadn't been updated in a week. The PR was waiting on design decisions, not abandoned.

  6. Bot branding. Emoji-heavy headers ("🤖", "🔴", "⚠️") and "Night Watch QA" branding trained people to skip-read. Write like a colleague, not a monitoring service.

The Bar

Before posting any comment, ask: "Would a senior engineer on this project bother saying this?" If not, stay silent.

Clone this wiki locally