Tech Lead Loop

The tech lead is the orchestrator of a multi-dev sprint. This skill defines the
standing loop the tech lead runs to keep development unblocked, enforce protocol,
and move the merge queue forward — without becoming a bottleneck.

The loop has five phases. You cycle through them continuously for the
duration of the sprint. Each phase has triggers, a checklist, and the specific
sub-skills / slash commands to invoke.

Never delegate understanding. This skill tells you what to check; you must
read the results and decide.

Principles

• Devs are authoritative for their own PRs. Tech lead only intervenes when a
  dev is truly stuck, when claims conflict, or when the merge queue stalls.
• TaskList is the canonical dispatch mechanism. Populate it at sprint start and whenever new issues are added mid-sprint. Devs self-serve — they claim tasks, self-merge, and claim the next task without waiting for tech lead direction.
• SendMessage only for escalations and exceptions. Devs contact tech lead only if TaskList is empty, they are blocked >30 min, or CI criteria force an escalation. Tech lead contacts devs only when they are stuck/silent or there is a file conflict to resolve.
• Every protocol correction issued to one dev should be generalized. If you
  correct one dev, broadcast the canonical protocol to all devs within the next
  cycle — individual corrections rot.
• Keep tool calls parallel when independent. One message with five Bash
  calls is dramatically faster than five sequential ones.
• Measure the merge queue, not the task queue. The right metric is
  "how many PRs are ready to merge but unmerged" — stalls there compound.

---

Phase 0 — Session start / context load

Trigger: fresh conversation, or resume after /compact or context rollover.

Checklist:

1. Read the current sprint doc: plan/issues/sprints/<N>/sprint.md
2. Read the tech lead handoff: plan/agent-context/tech-lead.md
3. git status && git branch --show-current && git log --oneline origin/main -10
4. gh pr list --state open --limit 20 — snapshot of inherited open PRs
5. ls .claude/worktrees/ — inherited worktrees (may contain WIP)
6. Read plan/method/file-locks.md if it exists — active dev claims
7. Read .claude/memory/MEMORY.md top section — critical rules + feedback index
8. TaskList — if empty, create tasks from plan/issues/sprints/{N}/ (current sprint dir, filter by status: ready) before touching any dev.

Output: before touching any dev, write a 3–5 sentence situation summary to
yourself (not to the user) covering baseline, open PRs, active dev claims,
known blockers. This is your working model.

Do not reply to the user with a situation recap — that's context waste.
Start doing Phase 1 work.

---

Phase 1 — Dispatch

Trigger: idle devs, TaskList is empty or has unclaimed tasks, unstarted sprint items.

Goal: TaskList is populated and every ready dev can self-serve.

Checklist:

1. Populate TaskList first. For each issue in plan/issues/sprints/{N}/ with status: ready that doesn't have a task yet: TaskCreate. If feasibility is hard and no impl spec exists, run /architect-spec first.
2. Count active devs vs unclaimed tasks. Target: up to 8 devs, each on a distinct issue, no two devs in the same function.
3. Idle notifications are normal — devs are between tasks and will self-claim. Do not ping unless they've been silent for >20 min with no commits (see Phase 3).
4. Conflict resolution — if two devs claim the same file/function: first specific-scope claim wins; message the later dev directly with a different task.

Only use SendMessage dispatch as fallback when a dev reports TaskList is empty and you can't immediately add a task (e.g., issue needs an arch spec first).

---

Phase 2 — Merge queue management

Trigger: a dev pushes a PR, a CI status feed update lands, or gh pr list
shows ≥3 open PRs.

Goal: the merge queue never stalls. A self-merge-eligible PR should land
within a few minutes of CI reporting.

Checklist:

1. Pull latest main: git pull --ff-only origin main
2. List open PRs with CI data:

   for p in $(gh pr list --state open --json number --jq '.[].number'); do
     cat .claude/ci-status/pr-$p.json 2>/dev/null | \
       jq -r '"PR #\(.pr) Δ\(.delta) impr=\(.improvements) regr=\(.regressions) ratio=\(.regressions * 100 / (.improvements // 1))%"'
   done

3. For each PR, classify:
   • Self-merge eligible (Δ>0, ratio<10%, scope≤5 files, no bucket>50):
     the dev should run /dev-self-merge. If they haven't, ping them.
   • Needs investigation (ratio≥10% or bucket>50): ping the owner with the
     specific gh run view <id> --log-failed command and a hypothesis about
     the regression cluster.
   • No owner / orphan (dev from an earlier session, dev non-responsive):
     you enqueue via gh pr merge <N> --auto (NO --merge/strategy flag — the queue owns the strategy and rejects --merge --auto; queue re-runs the required checks on the merged state). Reserve --admin --merge for true hotfix bypass.
   • Stale CI (new commits pushed after feed wrote): wait for fresh feed,
     don't merge until CI catches up.
4. If the queue has >5 self-merge-eligible PRs, send a broadcast reminding devs
   to merge their own PRs before starting new work (protocol point 6).
5. After merges land, baseline advances — remind devs to git merge main into
   their branches before pushing new commits.

Sub-skills / commands:

• /dev-self-merge — devs use this; you reference it in pings
• /pr-conflict-refresh — devs use this to rebase branches after main moves
• /merge-wave — for batched merges when the queue is deep
• /handle-regression — if a merged PR causes downstream breakage
• /bisect-regression — for tracking down which merge broke the baseline

---

Phase 3 — Stuck / silent dev triage

Trigger: a dev has gone silent for >20 minutes OR has only emitted idle
notifications since their last substantive message.

Goal: distinguish "genuinely working on something hard" from "hung /
inbox-broken" without pinging every 5 minutes.

Checklist:

1. Check the dev's worktree directly:

   WT=.claude/worktrees/issue-<N>-<slug>
   git -C $WT log --oneline main..HEAD  # recent commits
   git -C $WT diff --stat main..HEAD    # uncommitted scope
   stat -c '%y' $WT/src/**/*.ts 2>/dev/null | sort -r | head -5  # file modtimes

2. Check gh pr list --head <branch> — they may have silently pushed a PR
   without reporting it.
3. Interpret:
   • Recent commits + recent file modtimes: genuinely working. Do not ping.
   • No commits + no file modtimes + no PR + no messages: hung. Ping once
     with explicit reply requirement. If no reply in 10 minutes, either:
     (a) take over their PR yourself if one exists and is self-merge eligible,
     (b) spawn a replacement dev with the worktree state in the prompt,
     (c) mark the task for reassignment and move on.
   • PR exists, dev silent: this is protocol violation #1 (push=ping). Fetch
     the CI feed yourself and treat the PR as orphaned — admin-merge if clean,
     investigate regressions if not.
4. If the problem is "inbox delivery broken" (see
   .claude/memory/feedback_tasklist_sync_unreliable.md), fall back to
   SendMessage and do not trust their TaskList view.

Do not ping every few minutes. Between-turn idle notifications are normal
and do not indicate a hang.

---

Phase 4 — Protocol enforcement

Trigger: any individual protocol correction you issue to one dev.

Goal: implicit team norms become explicit, and every dev knows them.

Checklist:

1. Keep a mental list of corrections issued in the current session:
   • "push = ping"
   • "standdown = stop in place"
   • "self-merge before new work"
   • "file issue file before using the number in a PR title"
   • "work in worktrees, not /workspace"
   • "investigation PR is a valid output"
2. When you've issued ≥2 individual corrections covering the same theme, or
   you've corrected ≥2 different devs, broadcast a canonical protocol message
   to the full team (one message, 5–10 numbered points).
3. Request one-line acks. No ack within 10 minutes ⇒ direct follow-up per dev.
4. Log recurring patterns to memory as feedback rules:

   .claude/memory/feedback_<short-name>.md

   Follow the feedback type structure in the auto-memory system prompt.

Sub-skills / commands:

• /create-issue — for follow-up issues devs should file
• /architect-spec — for handing over hard issues to an architect

---

Phase 5 — Sprint hygiene

Trigger: every ~30 minutes during an active session, OR whenever the main
branch advances ≥5 PRs since your last cycle.

Goal: the sprint doc, issue files, and memory files reflect current reality.
Nothing important is trapped in conversation context only.

Checklist:

1. Update plan/issues/sprints/<N>/sprint.md "interim results" with the latest
   baseline and merge count.
2. Update completed issues in plan/issues/ —
   set frontmatter status: done.
3. Update plan/log/dependency-graph.md — strike through completed issues.
4. Write to memory before compacting: any new lesson, dev preference, or
   process rule that future sessions need. See
   .claude/memory/feedback_diary_and_sprints_before_compact.md.
5. Check token usage with /context — if approaching 40% of weekly budget,
   plan a compact boundary at the next natural pause.
6. Keep the handoff file plan/agent-context/tech-lead.md updated for any
   future fresh team restart. Don't wait for end-of-sprint — restart can
   happen at any time (see the inbox-delivery incident 2026-04-11).

Sub-skills / commands:

• /sprint-retrospective — at natural phase boundaries
• /session-wrapup — before /compact or session end
• /sprint-wrap-up — at sprint end, full closeout
• /regression-triage — when the harvester needs to run
• /analyze-regression — for specific regression bucket analysis

---

Loop summary

Phase 0: context load  (once per session start)
  ↓
┌─── Phase 1: dispatch (every idle dev, every new task)
│     ↓
│    Phase 2: merge queue (every push / every 5 min)
│     ↓
│    Phase 3: stuck triage (only when >20 min silence)
│     ↓
│    Phase 4: protocol enforcement (after ≥2 corrections)
│     ↓
│    Phase 5: sprint hygiene (every ~30 min)
│     ↓
│    [all devs shut down + no tasks?] ──→ Sprint-end wrap-up ──→ STOP
│     ↓ (no)
└─── (continue loop)

You don't always run every phase — you trigger on events. But you do
re-enter the loop after every user message, dev message, or tool result.
The sprint-end detection runs every iteration — when it triggers, the
wrap-up is mandatory before the loop can stop.

Sprint-end detection (MUST run before loop exit)

Trigger: all devs shut down AND no unclaimed/unblocked tasks remain.

When this condition is met, the sprint is over. You MUST complete the
wrap-up before stopping the loop. Do NOT just stop — incomplete wrap-ups
lose learnings, leave issues in the wrong state, and force the next
session to reconstruct context from scratch.

Sprint-end checklist (all mandatory, in order):

1. Tag: git tag sprint/<N>
2. Sprint doc: update plan/issues/sprints/<N>/sprint.md with:
   • Status: done in frontmatter
   • Ending baseline numbers
   • Results table (PRs merged, issues completed, issues deferred)
   • Acceptance criteria review (checked/unchecked)
   • Retrospective (what went well, what didn't, lessons learned)
3. Diary: append session entry to plan/diary.md
4. Handoff: update plan/agent-context/tech-lead.md for next session
5. Issues: move completed issues from ready/ to done/
6. Commit + push: stage all wrap-up files, commit, push, push tags
7. Landing page: verify Pages deploy triggered (baseline refresh uses
   [skip ci] which also skips deploy — trigger manually if needed)
8. Shutdown PO: if a PO agent is still alive, send shutdown request
9. TeamDelete: clean up team directories and worktrees
10. THEN stop the loop — omit ScheduleWakeup only after step 9

If you are about to omit ScheduleWakeup (stop the loop) and have NOT
completed steps 1-9, you are violating this protocol. Go back and do them.

When to pause or break the loop (non-sprint-end)

• User directly asks for something: handle the user request first, loop after.
• Token budget approaching 40%: Phase 5 hygiene + /compact.
• Fresh team restart needed: write plan/agent-context/tech-lead.md,
  TeamDelete, TeamCreate, resume from Phase 0.

Anti-patterns (do NOT do these)

• Stopping the loop without sprint wrap-up. "All devs shut down" is NOT
  the exit condition. "All devs shut down + wrap-up complete + tag pushed"
  is the exit condition. This is the #1 protocol violation — it happened in
  Sprint 41 and required the user to catch it.
• Polling devs every minute for status. Idle notifications are normal.
• Running /compact without updating the sprint doc first — lessons
  die with the context. See feedback_diary_and_sprints_before_compact.md.
• Merging your own tech-lead "pipeline restart" commits between dev
  merges. Doc commits force every open dev branch to re-merge main. Batch
  doc commits AFTER a merge wave completes.
• Taking a dev's work away without a direct SendMessage first. Standdown
  broadcasts are binding but devs need to see the message before they can
  honor it.
• Letting TaskList run empty. Devs have no way to self-serve when the queue is empty. Populate it before touching agents.
• Reading files you already read this session to "double-check". Your
  context is your source of truth; re-reading burns tokens and cache.
• Reporting merge progress to the user in full table form unless they ask
  for it. A one-sentence summary is almost always enough.
• Asking "do you want me to continue?" every few turns. The user will
  tell you to stop if they want to stop.

Cross-references

• CLAUDE.md — team config, merge protocol, memory budget
• plan/method/team-setup.md — roster, capacity limits
• .claude/skills/dev-self-merge/SKILL.md — what devs do after push
• .claude/skills/merge-wave/SKILL.md — batched merges
• .claude/skills/handle-regression/SKILL.md — when a merge breaks something
• .claude/skills/create-issue/SKILL.md — filing new issues
• .claude/skills/architect-spec/SKILL.md — hard-issue pre-work
• .claude/skills/sprint-wrap-up/SKILL.md — end of sprint
• .claude/memory/feedback_tasklist_sync_unreliable.md — why SendMessage is canonical
• .claude/memory/feedback_diary_and_sprints_before_compact.md — hygiene before /compact