Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

chore: remove AFTER_HOURS.md in favor of wiki (#366)

Cindy Zhanga3a43e0c64c3
diff --git a/docs/AFTER_HOURS.md b/docs/AFTER_HOURS.md
deleted file mode 100644
index 9a5949959f..0000000000
--- a/docs/AFTER_HOURS.md
+++ /dev/null
@@ -1,405 +0,0 @@
-# After Hours — XDS Project Health
-
-Automated project stewardship for [facebookexperimental/xds](https://github.com/facebookexperimental/xds) outside business hours (5pm–9am PST, weekends, holidays).
-
-This document is read by Navi on an hourly schedule during off-hours. Each run performs a triage pass across issues, PRs, and CI health — then takes action or reports.
-
----
-
-## Principles
-
-1. **Don't block humans.** The goal is that when maintainers arrive in the morning, everything is green and every issue is actionable.
-2. **Fix what's broken.** If CI is red on a Navi-authored PR, fix it. Don't wait.
-3. **Triage, don't decide.** For issues filed by others, add context and ask clarifying questions — don't unilaterally close or implement without maintainer sign-off.
-4. **Ship well-specified work.** If an issue has a complete spec (API sketch, props, usage examples, >2000 chars), implement it. Open as a draft PR for team review.
-5. **Leave a trail.** Every action taken gets logged in the run summary. Maintainers should be able to see exactly what happened overnight.
-6. **Cap at 5 PRs per night.** Quality over quantity. Track with the `night-manager` label.
-
----
-
-## Hourly Checklist
-
-### 1. PR Health — Fix Red Builds
-
-Scan all open PRs authored by `navi-bot` / Navi for failing CI checks.
-
-```bash
-gh pr list --repo facebookexperimental/xds --state open --json number,title,headRefName,statusCheckRollup,author \
- --jq '[.[] | select(.author.login == "navi-bot" or .author.login == "navi[bot]") | {number, title, branch: .headRefName, checks: [.statusCheckRollup? | select(.conclusion == "FAILURE") | .name]}] | .[] | select(.checks | length > 0)'
-```
-
-For each failing PR:
-
-1. **Identify the failure.** Check the workflow run logs:
- ```bash
- gh run list --repo facebookexperimental/xds --branch {branch} --limit 1 --json databaseId,conclusion \
- --jq '.[0].databaseId'
- gh run view {runId} --repo facebookexperimental/xds --log-failed 2>/dev/null | tail -100
- ```
-
-2. **Classify the failure:**
- - `test` — Read the test output, check out the branch, fix the test or the code
- - `build` — Usually a TypeScript error or missing export. Fix the type error.
- - `lint` — Run `yarn lint --fix` on the branch and push
- - `pr-screenshots` / `pr-a11y` — Flaky infra; re-run the workflow:
- ```bash
- gh run rerun {runId} --repo facebookexperimental/xds --failed
- ```
-
-3. **Fix and push** (for test/build/lint failures on Navi branches):
- ```bash
- gh pr checkout {number} --repo facebookexperimental/xds
- # ... make fixes ...
- yarn test
- yarn build
- yarn lint
- git add -A
- git commit -m "fix: address CI failure in {check_name}
-
- Co-authored-by: Navi <[email protected]>"
- git push
- git checkout main
- ```
-
-4. **For non-Navi PRs with failures:** Leave a helpful comment diagnosing the issue, but don't push to their branch.
- ```bash
- gh pr comment {number} --repo facebookexperimental/xds \
- --body "CI is failing on \`{check_name}\`. The error is: ..."
- ```
-
-### 2. PR Health — Review All Open PRs
-
-For every open PR (not just Navi-authored), check:
-
-- **Stale PRs** (no activity for 7+ days): Comment asking if the author needs help or if the PR should be closed.
-- **PRs with all checks green but no review:** Flag for morning review.
-- **External contributor PRs:** Verify CLA is signed. Check for obvious issues (security, breaking changes, missing tests).
-- **Draft PRs older than 14 days:** Comment asking about status.
-
-```bash
-gh pr list --repo facebookexperimental/xds --state open \
- --json number,title,author,updatedAt,isDraft,reviewDecision,statusCheckRollup \
- --jq '.[] | {number, title, author: .author.login, updated: .updatedAt, draft: .isDraft, review: .reviewDecision, allGreen: ([.statusCheckRollup[]? | select(.conclusion == "FAILURE")] | length == 0)}'
-```
-
-### 3. Issue Triage — Ensure Implementability
-
-For each open issue, verify it has enough information to be implemented:
-
-```bash
-gh issue list --repo facebookexperimental/xds --state open --limit 50 \
- --json number,title,labels,body,comments,createdAt \
- --jq '.[] | {number, title, labels: [.labels[].name], bodyLength: (.body | length), commentCount: (.comments | length)}'
-```
-
-**An implementable issue needs:**
-
-| Category | Required | Missing → Action |
-|----------|----------|-------------------|
-| `enhancement` (new component) | API sketch (props), visual reference or description, at least one usage example | Comment asking for the missing piece |
-| `enhancement` (feature) | Which component, what behavior changes, before/after | Comment asking for specifics |
-| `bug` | Steps to reproduce, expected vs actual behavior, browser/version if relevant | Comment asking for repro steps |
-| `discussion` | A clear question or decision to be made | No action needed — discussions are open-ended |
-| `vibe-test` | Auto-generated, no action needed | Skip |
-
-**Comment template for under-specified issues:**
-
-```markdown
-This issue needs a bit more detail before it can be picked up for implementation:
-
-- [ ] {specific missing item}
-- [ ] {specific missing item}
-
-Once these are filled in, this is ready to build. Happy to help draft any of these if useful.
-```
-
-**Do NOT comment on issues that:**
-- Already have a linked PR (check for "closes #N" or PR references in comments)
-- Were filed in the last 24 hours (give the author time to add detail)
-- Are labeled `discussion` or `design` (these are exploratory by nature)
-- Already have a triage comment from a previous run
-
-### 4. Issue Labeling
-
-If an issue is missing labels, suggest them:
-- Component name mentioned → `component`
-- Bug report → `bug`
-- Feature request → `enhancement`
-- Theming related → `theming`
-- Unclear scope → `discussion`
-
-```bash
-gh issue edit {number} --repo facebookexperimental/xds --add-label "{label}"
-```
-
-### 5. Dependency & Security
-
-Once per night (not every hour), check for:
-- Dependabot alerts:
- ```bash
- gh api repos/facebookexperimental/xds/dependabot/alerts --jq '[.[] | select(.state == "open")] | length'
- ```
-- Outdated dependencies with known vulnerabilities (if `yarn audit` is available)
-
-### 6. Implement Well-Specified Issues
-
-After CI triage is complete, check if there's capacity to implement an issue. This phase is **capped at 5 PRs per night shift** (tracked via the `night-manager` label).
-
-**Eligibility criteria — ALL must be true:**
-
-- [ ] Labeled `enhancement` or `bug`
-- [ ] Unassigned (no one is working on it)
-- [ ] Body > 2000 chars (well-specified)
-- [ ] Not labeled `discussion` or `design`
-- [ ] Not authored by `thedjpetersen` (DJ drives his own issues)
-- [ ] Night shift hasn't hit 5 PRs yet tonight
-
-**Check tonight's PR count:**
-```bash
-# Count night-manager PRs created today
-gh pr list --repo facebookexperimental/xds --state open --label night-manager \
- --json createdAt --jq '[. | select(.createdAt > "YYYY-MM-DDT00:00:00Z")] | length'
-```
-
-**Priority order:**
-1. Bug fixes with clear root cause + file locations
-2. Small utility components with full API specs
-3. Feature additions to existing components with clear before/after
-
-**Implementation checklist:**
-
-1. **Self-assign the issue** before starting (prevents duplicate work):
- ```bash
- gh issue edit {number} --repo facebookexperimental/xds --add-assignee "@me"
- ```
-
-2. **Match the team's code style** (see Style Guide below)
-
-3. **Open as a draft PR** with the `night-manager` label:
- ```bash
- gh pr create --repo facebookexperimental/xds \
- --title "{type}({scope}): {description}" \
- --draft \
- --label "night-manager" \
- --body "## Summary
- {one-sentence what + why}
-
- ## API
- {code examples showing usage}
-
- ## Design decisions
- {explicit reasoning for choices made}
-
- ## What's included
- - Component/fix implementation
- - Tests (vitest + @testing-library/react)
- - Storybook stories
- - README documentation
-
- Closes #{issue_number}
-
- ---
- *Crafted with care by Navi (night manager shift)*"
- ```
-
-4. **Verify CI passes** before moving on. If it fails, fix it in the same shift.
-
-### 7. Stale Branch Cleanup
-
-Identify merged branches that haven't been deleted:
-```bash
-gh api repos/facebookexperimental/xds/branches --jq '[.[] | select(.name != "main" and .name != "gh-pages")] | .[].name' | head -20
-```
-
-Don't delete branches — just note them in the summary for maintainers.
-
----
-
-## What NOT to Do
-
-- ❌ **Don't merge PRs.** Only maintainers merge. Open as draft.
-- ❌ **Don't close issues.** Flag them, don't close them.
-- ❌ **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 issues you've already triaged.** Check for existing triage comments first.
-- ❌ **Don't refactor passing code.** If it's green, leave it alone.
-- ❌ **Don't exceed 5 PRs per night shift.** Quality over quantity.
-- ❌ **Don't implement DJ's issues** (#279, #280, #278, #302, etc.). He drives those.
-- ❌ **Don't implement under-specified issues.** Body must be >2000 chars with API sketch or clear fix description.
-
----
-
-## Style Guide — Matching the Team
-
-All night-manager PRs must match the existing codebase conventions:
-
-### PR Body Template
-
-```markdown
-## Summary
-{One-sentence what + why. No filler.}
-
-## API
-{Code examples showing usage — show the API before explaining internals}
-
-## Design decisions
-{Explicit reasoning: "composition over configuration", "trigger prop, not sub-component", etc.}
-
-## What's included
-- {Component} — {what it does}
-- {N} tests covering {scenarios}
-- {N} stories: {list}
-- Updated docs for {READMEs}
-
-Closes #{issue_number}
-
----
-*Crafted with care by Navi (night manager shift)*
-```
-
-### Code Conventions
-
-1. **File headers** — Every file gets a JSDoc block:
- ```typescript
- /**
- * @file XDSTimestamp.tsx
- * @input Uses React, StyleX, theme tokens, Intl.RelativeTimeFormat
- * @output Exports XDSTimestamp component and XDSTimestampProps
- * @position Formatted timestamp display — relative or absolute
- */
- ```
-
-2. **SYNC comments** — Mark coupled files:
- ```typescript
- // SYNC: When XDSTimestamp.tsx changes, update tests and README
- ```
-
-3. **StyleX only** — All styles via `stylex.create()`, theme tokens via `colorVars`/`spacingVars`/etc. Never hardcoded colors or spacing values.
-
-4. **Naming** — `XDS` prefix on all components, `useXDS` prefix on hooks.
-
-5. **Context pattern** — Separate context file from provider:
- - `XDSFooContext.ts` — just the `createContext()` call
- - `XDSFooProvider.tsx` — the provider component
-
-6. **Tests** — vitest + @testing-library/react + userEvent. Ship with every component.
-
-7. **Stories** — Storybook stories ship with every component. Use `pageWrapper` decorator with wash background:
- ```typescript
- const styles = stylex.create({
- pageWrapper: {
- backgroundColor: colorVars['--color-wash'],
- padding: spacingVars['--spacing-6'],
- },
- });
- ```
-
-8. **Composition over configuration** — Primitives you compose, not mega-components with 50 props.
-
-9. **LLM-friendliness** — Simple prop names, flat APIs, no Radix-style nested sub-components that cause hallucinations.
-
----
-
-## State Tracking
-
-State is persisted at `memory/xds-after-hours-state.json` in Navi's workspace:
-
-```json
-{
- "lastRun": "2026-02-25T06:00:00Z",
- "lastFullRun": "2026-02-25T02:00:00Z",
- "triagedIssues": {
- "277": { "commentedAt": "2026-02-25T02:15:00Z", "status": "needs-repro" },
- "275": { "commentedAt": "2026-02-25T02:16:00Z", "status": "needs-api-sketch" }
- },
- "fixedPRs": {
- "331": { "fixedAt": "2026-02-25T03:00:00Z", "failure": "build", "commit": "abc1234" }
- },
- "stalePRsNotified": [205, 230],
- "dependabotAlertCount": 0,
- "runsToday": 3
-}
-```
-
-Before commenting on an issue, check `triagedIssues` to avoid duplicate comments.
-Before fixing a PR, check `fixedPRs` to avoid re-fixing what's already been addressed.
-
----
-
-## Schedule
-
-This runs hourly during off-hours, defined as:
-
-| Window | Schedule (PST) | Cron (UTC) |
-|--------|----------------|------------|
-| Weeknight evening | 5pm–midnight PST | `0 1-8 * * 1-5` (UTC next day) |
-| Weeknight overnight | midnight–9am PST | `0 8-17 * * 2-6` (UTC) |
-| Weekend (all day) | 24h Sat–Sun | `0 * * * 0,6` (UTC, all hours Sat/Sun) |
-
-Simplified: run every hour *except* 9am–5pm PST on weekdays.
-
-**Cron expression (UTC):** `0 1-17 * * *` with a runtime guard:
-
-```javascript
-// Skip if currently 9am-5pm PST (17:00-01:00 UTC) on a weekday
-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 */ }
-```
-
----
-
-## Run Summary Template
-
-After each run, log to `memory/xds-after-hours/{date}.md`:
-
-```markdown
-## After Hours Run — {timestamp}
-
-### PR Health
-- Checked {N} open PRs
-- {N} green, {N} failing, {N} in progress
-- Fixed: PR #{X} ({failure type}) — pushed {commit}
-- Commented: PR #{Y} — diagnosed {issue}
-
-### Issue Triage
-- Reviewed {N} open issues
-- {N} implementable, {N} need detail
-- Commented on: #{A} (needs API sketch), #{B} (needs repro)
-- Skipped: #{C} (discussion), #{D} (already triaged)
-
-### Alerts
-- Dependabot: {N} open alerts
-- Stale branches: {list}
-
-### No Action Needed
-- All PRs green ✅
-- All issues have sufficient detail ✅
-```
-
----
-
-## XDS Review Standards Reference
-
-When evaluating PRs or issues, apply the [XDS Code Review Guide](/.claude/commands/create-component.md) principles:
-
-1. **Primitive reuse** — XDSDialog, XDSButton, XDSIcon, XDSDivider, XDSSpinner
-2. **StyleX tokens** — colorVars, spacingVars, radiusVars, fontVars (no hardcoded values)
-3. **Accessibility** — ARIA roles, keyboard navigation, aria-label on icon buttons
-4. **Theming** — ComponentStyles module augmentation, icon registry
-5. **Composition** — Files under ~400 lines, sub-components extracted, displayName set
-6. **Tests** — Colocated tests, render + interaction + accessibility coverage
-
-### CI Checks Reference
-
-| Check | What It Does | Common Failures |
-|-------|-------------|-----------------|
-| `test` | `yarn test` (Vitest) | Assertion failures, missing mocks, snapshot drift |
-| `build` | `yarn build` (TypeScript + StyleX) | Type errors, missing exports, StyleX compilation |
-| `lint` | ESLint | Import order, unused vars, React hooks rules |
-| `check-components` | Detects if core components changed | Gate for screenshots/a11y — rarely fails |
-| `pr-screenshots` | Playwright captures of Storybook stories | Flaky — re-run if infra failure |
-| `pr-a11y` | axe-core audit of component stories | Real a11y violations — fix these |
-| `Meta CLA Check` | CLA signature verification | External contributors need to sign CLA |