startup
Review essential documentation and context at session start. Use when beginning a new session to load AI rules, git state, and pending tasks.
When & Why to Use This Skill
The Session Startup skill is a comprehensive initialization tool designed to synchronize Claude's operational context with the current state of a development project. It automates the review of essential documentation (such as CLAUDE.md and AI Rules of Engagement), verifies Git branch status, and checks for pending tasks in HUMAN_TODO.md. By validating system health—including Docker, MCP, and RAG availability—it ensures the agent is fully prepared and aligned with project-specific guidelines before any work begins, significantly reducing errors caused by missing context.
Use Cases
- Initial Session Alignment: Use at the start of a new work session to load project-specific rules, coding standards, and the current task list to ensure the AI is fully up-to-date.
- Git State Verification: Automatically check current branches, uncommitted changes, and synchronization with origin/main to prevent merge conflicts or divergent histories.
- System Health & Dependency Check: Verify that critical infrastructure like Docker containers, MCP tools, and RAG services are healthy and accessible before performing complex operations.
- PR & Feedback Review: Identify pending Codex feedback or GitHub PR comments at the start of a session to prioritize addressing reviews over new feature development.
- Environment Readiness: Confirm that the local environment is properly configured and that all necessary documentation is acknowledged to maintain high code quality and workflow consistency.
| name | startup |
|---|---|
| description | Review essential documentation and context at session start. Use when beginning a new session to load AI rules, git state, and pending tasks. |
| model_tier | haiku |
| can_parallel_with | [check-codex] |
| must_serialize_with | [] |
| preferred_batch_size | 1 |
| max_file_context | 40 |
| compression_level | 2 |
| requires_git_context | true |
| requires_db_context | false |
| - pattern | "behind.*main" |
| reason | "Branch sync decisions need human input" |
Session Startup Skill
Purpose: Review essential documentation and context at the start of each session Created: 2025-12-27 Trigger:
/startupcommand 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)
6. Check Resilience Status (REQUIRED)
If MCP is available, ALWAYS check system resilience:
# Get current defense level
mcp__residency-scheduler__get_defense_level_tool(coverage_rate=0.95)
Interpret results:
- GREEN (Level 1-2): Normal operations, proceed with work
- YELLOW (Level 3): Increased monitoring, be cautious with changes
- ORANGE (Level 4): Elevated risk, avoid schedule modifications
- RED (Level 5): Critical issues, escalate to human
Include defense level in session output. If ORANGE or RED, flag as blocker.
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/mainis 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 --fixandruff format .before PRs - Run
npm run lint:fixfor 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
| Skill | When to Use |
|---|---|
check-codex |
View detailed Codex feedback (rate-limiting step before merge) |
session-documentation |
End of session handoff |
systematic-debugger |
Complex bug investigation |
safe-schedule-generation |
Before schedule modifications |
pr-reviewer |
Before creating PRs |
Related Protocols
| Protocol | When to Use |
|---|---|
| CCW Burn Protocol | Before running parallel CCW task burns (20+ tasks) |
| PLAN_PARTY Protocol | Complex task planning (after reconnaissance or standalone) |
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-checkmust 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.