ci-iteration

name	ci-iteration
description	This skill should be used when running CI checks iteratively and fixing failures. Use when executing make targets (fast-ci, all-ci, ci), iterating on lint/format/type/test errors, or needing the devrun agent pattern for pytest/ty/ruff/prettier/make/gt commands.
metadata	{"internal":true}

CI Iteration

Overview

Run the specified CI target and automatically fix any failures. Keep iterating until all checks pass or you get stuck on an issue that requires human intervention.

IMPORTANT: All make commands must be run from the repository root directory. The Makefile is located at the root of the repository, not in subdirectories.

Sub-Agent Policy

CRITICAL: When spawning sub-agents to run make, pytest, ty, ruff, prettier, or gt commands, you MUST use devrun:

Task tool with:
- subagent_type: devrun  <- MUST be devrun, NEVER general-purpose

Why: devrun has hard tool constraints (no Edit/Write) preventing destructive changes. The parent agent (you) processes reports and applies fixes - sub-agents only report.

FORBIDDEN:

• Spawning general-purpose or other sub-agents for make/pytest/ty/ruff/prettier/gt
• Giving sub-agents prompts like "fix issues" or "iterate until passing"

REQUIRED:

• Sub-agents run ONE command and report results
• Parent agent decides what to fix based on reports

Core Workflow

1. Initial Run

Use the devrun agent to run the specified make target from the repository root:

Task tool with:
- subagent_type: devrun
- description: "Run [make target] from repo root"
- prompt: "Change to repository root and execute: [make target]"

2. Parse Failures

Analyze the output to identify which check(s) failed:

• Ruff lint failures: "ruff check" errors
• Format failures: "ruff format --check" or files needing reformatting
• Prettier failures: Markdown files needing formatting
• MD-check failures: CLAUDE.md files not properly referencing AGENTS.md
• ty failures: Type errors with file paths and line numbers
• Test failures: pytest failures with test names and assertion errors

3. Apply Targeted Fixes

Based on failure type, apply appropriate fixes:

Failure Type	Fix Command
Ruff lint	make fix via devrun
Ruff format	make format via devrun
Prettier	make prettier via devrun
Sync-Kit	erk sync directly
MD-check	Edit CLAUDE.md to contain only @AGENTS.md
ty	Edit files to fix type annotations
Tests	Read and edit source/test files

4. Verify and Repeat

After applying fixes, run the make target again via devrun. Continue the cycle: run -> identify failures -> fix -> verify.

Iteration Control

Safety Limits:

• Maximum iterations: 10 attempts
• Stuck detection: If the same error appears 3 times in a row, stop
• Progress tracking: Use TodoWrite to show iteration progress

Progress Reporting

Use TodoWrite to track progress:

Iteration 1: Fixing lint errors
Iteration 2: Fixing format errors
Iteration 3: Fixing type errors in src/erk/cli/commands/switch.py
Iteration 4: All checks passed

When to Stop

SUCCESS: Stop when the make target exits with code 0 (all checks passed)

STUCK: Stop and report to user if:

1. You've completed 10 iterations without success
2. The same error persists after 3 fix attempts
3. You encounter an error you cannot automatically fix

Reporting Formats

Success Format

## Finalization Status: SUCCESS

All CI checks passed after N iteration(s):

(check) **Lint (ruff check)**: PASSED

(check) **Format (ruff format --check)**: PASSED

(check) **Prettier**: PASSED

(check) **AGENTS.md Standard (md-check)**: PASSED

(check) **ty**: PASSED

(check) **Tests**: PASSED

(check) **Sync-Kit (erk check)**: PASSED

The code is ready for commit/PR.

IMPORTANT: Each check line MUST be separated by a blank line in the markdown output to render properly in the CLI.

Stuck Format

## Finalization Status: STUCK

I was unable to resolve the following issue after N attempts:

**Check**: [lint/format/prettier/md-check/ty/test]

**Error**:
[Exact error message]

**File**: [file path if applicable]

**Attempted Fixes**:

1. [What you tried first]
2. [What you tried second]
3. [What you tried third]

**Next Steps**:
[Suggest what needs to be done manually]

Guidelines

1. Be systematic: Fix one type of error at a time
2. Run full CI: Always run the full make target, not individual checks
3. Use devrun agent: Always use the Task tool with devrun agent for ALL make commands
4. Run from repo root: Always ensure make commands execute from repository root
5. Track progress: Use TodoWrite for every iteration
6. Don't guess: Read files before making changes
7. Follow standards: Adhere to AGENTS.md coding standards
8. Fail gracefully: Report clearly when stuck
9. Be efficient: Use targeted fixes (don't reformat everything for one lint error)

Example Flow

Iteration 1:
- Use Task tool with devrun agent to run make target from repo root
- Found: 5 lint errors, 2 files need formatting
- Fix: Use Task tool with devrun agent to run make fix, then make format from repo root
- Result: 3 lint errors remain

Iteration 2:
- Use Task tool with devrun agent to run make target from repo root
- Found: 3 lint errors (imports)
- Fix: Edit files to fix import issues
- Result: All lint/format pass, 2 type errors

Iteration 3:
- Use Task tool with devrun agent to run make target from repo root
- Found: 2 ty errors in switch.py:45 and switch.py:67
- Fix: Add type annotations
- Result: All checks pass

SUCCESS

Important Reminders

• NEVER run pytest/ty/ruff/prettier/make/gt directly via Bash
• Always use the Task tool with subagent_type: devrun
• Covered tools: pytest, ty, ruff, prettier, make, gt
• Always ensure make commands execute from the repository root directory