Skip to main content
Agent skill

Tech Lead Loop

The tech lead's standing loop for keeping development unblocked across a sprint. Defines phase-by-phase protocol enforcement, merge-queue monitoring, and escalation triggers. Invoke at session start, again after every significant state change, and whenever devs look idle.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Tech Lead Loop when an AI agent needs a reusable SKILL.md workflow for this job: The tech lead's standing loop for keeping development unblocked across a sprint. Defines phase-by-phase protocol enforcement, merge-queue monitoring, and escalation triggers. Invoke at session start, again after every significant state change, and whenever devs look idle.

When not to use it

Skip Tech Lead Loop when the task is outside the analysis category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/tech-lead-loop
# Save SKILL.md to ~/.claude/skills/tech-lead-loop/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/tech-lead-loop/SKILL.md. For a shared project, commit the folder at .claude/skills/tech-lead-loop/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Tech Lead Loop skill for this task: Use Tech Lead Loop when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
58/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# 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: ```bash 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: ```bash 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

Intended uses

  • Use Tech Lead Loop when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.