Startup

Session Startup Skill

Purpose: Review essential documentation and context at the start of each session Created: 2025-12-27 Trigger: /startup command or session start Aliases: /session-start, /ready

When to Use

Run /startup at the beginning of every session to:

• Review AI Rules of Engagement
• Check current git state and branch
• Review pending tasks from HUMAN_TODO.md
• Identify blockers or in-progress work
• Confirm readiness to work

Required Actions

When this skill is invoked, Claude MUST:

1. Review Core Documentation

Read these files in order:

1. CLAUDE.md                                    # Project guidelines
2. docs/development/AI_RULES_OF_ENGAGEMENT.md   # Git/PR workflow rules
3. HUMAN_TODO.md                                # Current tasks and priorities
4. docs/development/DEBUGGING_WORKFLOW.md       # Debugging methodology (skim)
5. docs/development/CI_CD_TROUBLESHOOTING.md    # Common CI issues (skim)

2. Check Git Context

Run these commands:

# Current branch
git branch --show-current

# Recent commits on this branch
git log --oneline -5

# Check for uncommitted changes
git status --porcelain

# Check for other AI branches in progress
git branch -r | grep -E 'claude/|codex/|ai/' | head -5

# Check if behind origin/main
git fetch origin main && git rev-list --count HEAD..origin/main

3. Check Codex Feedback (if PR exists)

If current branch has an open PR, check for Codex feedback. Codex (GitHub AI) reviews PRs and is the rate-limiting step before merge.

PR_NUMBER=$(gh pr view --json number -q '.number' 2>/dev/null)
if [ -n "$PR_NUMBER" ]; then
  REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
  CODEX_COUNT=$(gh api repos/${REPO}/pulls/${PR_NUMBER}/comments \
    --jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]")] | length' 2>/dev/null || echo "0")

  if [ "$CODEX_COUNT" -gt 0 ]; then
    echo "Codex Feedback: ${CODEX_COUNT} comment(s) pending - run /check-codex"
  fi
fi

4. Check System Health (Optional)

If Docker is running:

# Container status
docker compose ps 2>/dev/null || echo "Docker not running"

# Backend health
curl -s http://localhost:8000/health 2>/dev/null || echo "Backend not available"

5. Check MCP/RAG Health (CRITICAL)

Without MCP, Claude Code loses access to RAG and 30+ scheduling tools.

# Check MCP container
MCP_STATUS=$(docker inspect scheduler-local-mcp --format '{{.State.Health.Status}}' 2>/dev/null || echo "not running")
if [ "$MCP_STATUS" != "healthy" ]; then
  echo "⚠️  WARNING: MCP container is $MCP_STATUS"
  echo "   Claude Code has NO RAG access and NO MCP tools!"
  echo "   Run: ./scripts/start-local.sh"
fi

Then verify RAG is accessible by calling mcp__residency-scheduler__rag_health.

If RAG check fails with 401 or connection error:

⚠️  CRITICAL: RAG/MCP NOT AVAILABLE
   - Cannot search knowledge base
   - Cannot use scheduling MCP tools
   - Cannot validate ACGME compliance via MCP

   Fix: ./scripts/start-local.sh (starts all services including MCP)

Output Format

Provide a concise summary in this format:

## Session Ready

**Branch:** `claude/current-task`
**Status:** Clean working tree / X uncommitted changes
**Behind main:** 0 commits / X commits (rebase needed)

### Codex Feedback
- **Status:** [N] comment(s) pending (run `/check-codex` for details)
- **Or:** No Codex feedback yet (typically 1-10 min after PR)
- **Or:** No PR for current branch

### Key Rules Acknowledged
- origin/main is sacred - PRs only
- Backup before database modifications
- Run linters before PR (ruff, npm lint)

### Current Priorities (from HUMAN_TODO.md)
1. [Priority item 1]
2. [Priority item 2]
3. [Priority item 3]

### Blockers/In-Progress
- [Any blocked items or WIP from previous sessions]
- [Codex P1 issues flagged as blockers if present]

### System Status
- Backend: Running/Not running
- Database: X assignments in Block Y
- MCP: healthy/unhealthy/not running
- RAG: X documents indexed / unavailable

**⚠️ If MCP unavailable:** Run `./scripts/start-local.sh`

Ready to work. What's the task?

Key Rules to Acknowledge

Every startup should confirm understanding of:

Git Workflow

• origin/main is the single source of truth
• Always create feature branches from origin/main
• Never push directly to main - use PRs
• Never force push without explicit approval

MCP Safety

• Database-modifying operations require backup + approval
• Read-only operations are always safe

Code Quality

• Run ruff check --fix and ruff format . before PRs
• Run npm run lint:fix for frontend
• Tests must pass before commit

Debugging Approach

• Explore first, fix second
• Write failing tests before fixing bugs
• Use "think hard" / "ultrathink" for complex issues

Quick Reference Card

HARD STOPS (ask user):
- Divergent histories
- Force push required
- Protected branch modification
- Merge conflicts

SAFE COMMANDS (always OK):
git status, git diff, git log, git branch, git fetch

BEFORE EVERY COMMIT:
cd backend && ruff check . --fix && pytest
cd frontend && npm run lint:fix && npm test

Related Skills

Related Protocols

CCW Burn Key Points:

• Validate every 20 tasks (build + type-check gate)
• Watch for token concatenation bugs (await sawait ervice)
• Pre-burn: npm run build && npm run type-check must pass

Example Invocation

User: /startup

Claude:

## Session Ready

**Branch:** `claude/fix-mcp-namespace-collision`
**Status:** Clean working tree
**Behind main:** 0 commits

### Codex Feedback
- **Status:** 2 comment(s) pending (run `/check-codex` for details)

### Key Rules Acknowledged
- origin/main is sacred - PRs only
- Backup before database modifications
- Run linters before PR

### Current Priorities (from HUMAN_TODO.md)
1. UI/UX: Frozen headers on schedule grid
2. Heatmap: Add block navigation
3. Backend: Fix faculty rotation_template_id assignment

### Blockers/In-Progress
- FastMCP upgrade blocked on URI template changes (see MCP_FASTMCP_UPGRADE_NEEDED.md)
- Codex feedback pending (2 comments) - address before merge

### System Status
- Backend: Running (Docker)
- Database: 87 assignments in Block 10

Ready to work. What's the task?

This skill ensures every session starts with proper context and rule awareness.