Timmy-time-dashboard/timmy_automations/daily_run/README.md

Daily Run Automations

Scripts that run periodically to keep the development loop operational.

Scripts

Script	Source	Purpose	Trigger
cycle_retro.py	../../scripts/cycle_retro.py	Log structured retrospective data	Post-cycle
loop_guard.py	../../scripts/loop_guard.py	Idle detection with exponential backoff	Pre-cycle
triage_score.py	../../scripts/triage_score.py	Mechanical issue scoring	Every 10 cycles
orchestrator.py	orchestrator.py	The 10-minute ritual — Daily Run agenda + review	Manual

Running

These scripts are invoked by the dev loop orchestrator (Hermes). Manual execution:

# After a successful cycle
python3 scripts/cycle_retro.py --cycle 42 --success --issue 123 --type bug

# Check if queue has work (exits 0 if ready, 1 if idle)
python3 scripts/loop_guard.py

# Score open issues
python3 scripts/triage_score.py

# Generate Daily Run agenda (10-minute ritual)
python3 timmy_automations/daily_run/orchestrator.py

# Generate agenda with day summary (review mode)
python3 timmy_automations/daily_run/orchestrator.py --review

# Output as JSON
python3 timmy_automations/daily_run/orchestrator.py --review --json

# Use a focus-day preset (see Focus-Day Presets section below)
python3 timmy_automations/daily_run/orchestrator.py --preset tests-day

# List available presets
python3 timmy_automations/daily_run/orchestrator.py --list-presets

Daily Run Orchestrator

The orchestrator script connects to local Gitea and:

1. Fetches candidate issues matching configured labels (default: daily-run + size:XS/size:S)
2. Generates a concise agenda with up to 3 items for approximately 10 minutes of work
3. Review mode (--review): Summarizes the last 24 hours — issues/PRs touched, items closed/merged, test failures
4. Focus-Day Presets (--preset): Biases the agenda toward specific types of work

Configuration

Edit timmy_automations/config/daily_run.json under the orchestrator section:

{
  "orchestrator": {
    "candidate_labels": ["daily-run"],
    "size_labels": ["size:XS", "size:S"],
    "max_agenda_items": 3,
    "lookback_hours": 24,
    "agenda_time_minutes": 10
  }
}

Option	Description	Default
candidate_labels	Labels to identify Daily Run candidates	["daily-run"]
size_labels	Size labels to filter by	["size:XS", "size:S"]
max_agenda_items	Maximum items in agenda	3
lookback_hours	Hours to look back in review mode	24
agenda_time_minutes	Target time budget for agenda	10

Environment Variables

Override config via environment:

export TIMMY_GITEA_API="http://localhost:3000/api/v1"
export TIMMY_REPO_SLUG="rockachopa/Timmy-time-dashboard"
export TIMMY_GITEA_TOKEN="your-token-here"  # Alternative to token file

Output Format

Standard mode:

============================================================
📋 DAILY RUN AGENDA
============================================================
Generated: 2026-03-21T15:16:02+00:00
Time budget: 10 minutes
Candidates considered: 5

1. #123 [XS] [infra]
   Title: Fix config loading bug
   Action: FIX
   URL: http://localhost:3000/rockachopa/Timmy-time-dashboard/issues/123
...

Review mode (--review): Adds a day summary section showing issues touched, closed, PRs merged, and any test failures.

Focus-Day Presets

Focus-day presets bias the Daily Run agenda toward specific types of work. Use --preset <name> to activate a preset.

Preset	Description	Candidate Labels	Use When
tests-day	Focus on test-related work	test, testing, tests, coverage	Improving test coverage, fixing flaky tests
triage-day	Issue triage and backlog grooming	triage, backlog, needs-review, grooming	Organizing the backlog, reviewing stale issues
economy-day	Payment and economic features	economy, payment, pricing, l402, lightning, bitcoin	Working on Lightning/L402 integration
docs-day	Documentation and guides	docs, documentation, readme, guide	Writing docs, updating READMEs
refactor-day	Code cleanup and refactoring	refactor, cleanup, debt, tech-debt	Paying down technical debt

How Presets Work:

1. Label Filtering: Each preset defines its own candidate_labels — issues with any of these labels are fetched
2. Size Filtering: Presets can include larger sizes (e.g., tests-day includes size:M for bigger test refactors)
3. Priority Boosting: Issues matching preset priority labels get a scoring bonus (+15 for labels, +8 for title keywords)
4. Title Filtering: Some presets filter by title keywords to find relevant issues even without labels
5. Custom Agenda Title: The output header reflects the focus (e.g., "🧪 Tests Day — Focus on Quality")

Example:

# Run with tests-day preset
$ python3 timmy_automations/daily_run/orchestrator.py --preset tests-day

============================================================
🧪 Tests Day — Focus on Quality
============================================================
Generated: 2026-03-21T15:16:02+00:00
Time budget: 10 minutes
Candidates considered: 5
Focus preset: tests-day

1. #123 [M] [infra]
   Title: Add integration tests for payment flow
   Action: TEST
   URL: http://localhost:3000/rockachopa/Timmy-time-dashboard/issues/123

Extending Presets

Presets are defined in timmy_automations/config/daily_run.json under focus_day_presets. To add a new preset:

{
  "focus_day_presets": {
    "my-preset": {
      "description": "What this preset is for",
      "candidate_labels": ["label-1", "label-2"],
      "size_labels": ["size:XS", "size:S"],
      "title_keywords": ["keyword1", "keyword2"],
      "priority_boost": ["label-1"],
      "agenda_title": "🎯 My Preset — Description"
    }
  }
}

Configuration

See ../config/automations.json for automation manifests and ../config/daily_run.json for scheduling, orchestrator settings, and focus-day presets.