Nightly Routine

Overview

Automated end-of-day maintenance that ensures clean project state before leaving for the day.

Core principle: Leave the codebase in a clean, resumable state with zero manual overhead.

Trigger: End of work day, before closing Claude Code

Duration: ~10-15 seconds (vs. ~60 seconds manual)

Sleep Score (0-100)

See examples/scoring-system.md for complete scoring documentation.

Comprehensive health check across 7 dimensions:

Check	Points	Criteria
Uncommitted work saved	20	No uncommitted changes OR committed
Branches cleaned	15	No stale merged branches
Session branches clean	10	No stale unmerged session branches
Issues updated	20	Today's issues have status updates
CI passing	15	Latest CI run successful
Services stopped	10	No dev services running
Logs archived	10	Session logs saved

Branch Protection Impact (Issue #142):

• Warning: ⚠️ PROTECTED indicator if on protected branch with uncommitted work
• Recommendation: Create feature branch before committing

Score Interpretation:

• 90-100: Perfect shutdown - ready for tomorrow
• 70-89: Good - minor cleanup needed
• 50-69: Fair - some uncommitted work or failed CI
• 0-49: Poor - significant cleanup required

Workflow

Five-step process:

1. Collect Project State - Using capture_state.py (git, GitHub, services)
2. Calculate Sleep Score - Using sleep_score.py module
3. Generate Nightly Report - Using report_generator.py module
4. Capture Session State - Update STATUS.json via pop-session-capture
5. Present Report to User - Display score, breakdown, and recommendations

Data Collection

Consolidated commands:

• Git: Branch, last commit, status, stashes, merged branches
• GitHub: Open issues (last 5), latest CI run
• Services: Running processes, session logs

All wrapped in capture_state.py for consistent error handling.

Integration

Key utilities:

• capture_state.py - Complete project state capture
• routine_measurement.py - Performance tracking (when using --measure)
• routine_cache.py - GitHub data caching (when using --optimized)

Performance:

• Tool call reduction: 64% (11 → 4 calls)
• Execution time: 75-83% faster (60s → 10-15s)
• Token reduction: 40-96% (with --optimized)

Output Format

Report includes:

• Sleep Score (0-100) with visual indicator
• Score breakdown table
• Uncommitted changes list (if any)
• Session branches status (active during the day, unmerged, stale)
• Recommendations before leaving (including branch cleanup)
• Encouraging Bible verse (Issue #71)
• Next morning actions

Session Branches

The nightly routine checks for session branches that were active during the day and flags cleanup opportunities.

Checks performed:

• Active branches: Lists all unmerged session branches
• Day activity: Shows branches that were created or switched to during the day
• Stale detection: Flags branches older than 3 days for cleanup
• Cleanup suggestions: Recommends merging or deleting stale branches

Scoring impact (10 points):

• 10/10: No unmerged session branches
• 5/10: 1-2 unmerged branches, none older than 3 days
• 0/10: 3+ unmerged branches or any branch older than 3 days

Report output example:

## Session Branches

**Active during today**: 2 branches used
**Unmerged**: 3 branches

| Branch         | Reason                    | Age    | Status    |
|----------------|---------------------------|--------|-----------|
| auth-bug       | Token expiry investigation | 1 day  | Active    |
| cache-research | Redis vs Memcached spike   | 4 days | STALE     |
| test-debug     | Flaky test investigation   | 6 days | STALE     |

Recommendations:
- Merge "auth-bug" with outcome before leaving
- Delete or merge stale branches: cache-research (4d), test-debug (6d)

Next Actions (The PopKit Way)

CRITICAL: Always end with AskUserQuestion to keep PopKit in control.

Context-aware options based on score:

• Score < 70: Commit and push (Recommended), stash changes, or review files
• Score >= 70: Review tomorrow's priorities, check CI, or end session
• Services running: Stop all services (Recommended) or leave running
• CI failing: Investigate now, note for morning, or check logs

Never just show a report and end the session!

Error Handling

Graceful degradation:

• Git not available → Skip git checks, continue with partial score
• GitHub CLI not available → Skip GitHub checks, continue with partial score
• Service check failures → Assume services stopped (safe default)

Never block - provide best possible score with available data.

Usage Examples

# Basic usage
/popkit:routine nightly

# With measurement
/popkit:routine nightly --measure

# Quick summary
/popkit:routine nightly quick

# With optimization (caching)
/popkit:routine nightly --optimized

Related Skills

• pop-session-capture: Updates STATUS.json (invoked automatically)
• pop-session-branch: Session branching for side investigations
• pop-morning: Morning counterpart with Ready to Code score
• pop-routine-optimized: Optimized execution with caching

Related Commands

• /popkit:routine nightly: Main entry point
• /popkit:routine morning: Morning routine
• /popkit:next: Context-aware next action recommendations

Success Criteria

✅ Sleep Score accurately reflects project state ✅ STATUS.json always updated correctly ✅ Completes in <20 seconds ✅ Provides actionable recommendations ✅ Reduces manual workflow by 64%

---

Skill Type: Automated Routine Category: Workflow Automation Tier: Core (Always Available) Version: 1.0.0