**Determine the starting point:**

| State | Next Step |
|-------|-----------|
| On base branch with uncommitted changes | Step 2 (create branch) |
| On feature branch with uncommitted changes | Step 3 (commit) |
| On feature branch with commits, nothing uncommitted | Step 4 (sync) |
| PR already exists for this branch | Inform user, ask whether to update or monitor CI |
| No changes anywhere | Inform user "No changes detected. Nothing to do." and stop |

**Update task with branch info:**

• taskId: [pr task ID]
• subject: "Create PR: [actual-branch-name]"
• metadata: {"branch": "[branch-name]", "baseBranch": "[base-branch]"}

undefined

git checkout -b <descriptive-branch-name>

• feat/short-description

  for features

• fix/short-description

  for bug fixes

• refactor/short-description

  for refactoring

• docs/short-description

  for documentation

git add -A

git status
git add <file1> <file2> ...
git diff --cached --stat
git commit -m "$(cat <<'EOF'
<type>: <short summary>

<optional longer description>
EOF
)"

feat:

fix:

refactor:

docs:

test:

chore:

1. Read the error output to understand what the hook requires
2. Fix the flagged issues
3. Stage the fixed files
4. Create a new commit (do NOT amend the previous commit)

git fetch origin
git log --oneline HEAD..origin/<base-branch> | head -20

AskUserQuestion

1. Rebase (recommended when no PR exists yet)
2. Merge (safer with many commits or shared branches)
3. Skip (proceed without syncing)

git log --oneline <base-branch>..HEAD
git diff <base-branch>...HEAD --stat

• Title: Under 70 characters, describes the change
• Body: Start with issue references on the first line (e.g.

  Closes #45

  ), then a structured description:

[issue references: Fixes #...]

AskUserQuestion

AskUserQuestion

Here's what I'll do next:

1. Run local checks (if available for this project)
2. Push the branch to origin
3. Create the PR with the approved title and body
4. Monitor CI and fix any failures

I'll auto-fix small issues (formatting, lint, type errors, test failures). If anything bigger comes up, I'll check with you first.

Ready to proceed?

1. CLAUDE.md or AGENTS.md in the project root (may specify lint, test, build commands)
2. Project config files:

   package.json

   (scripts),

   Makefile

   ,

   pyproject.toml

   ,

   DESCRIPTION

   ,

   Justfile

   ,

   Taskfile.yml

   , etc.
3. CI workflow files in

   .github/workflows/

   to understand what CI will run

• Lint/format:

  npm run lint

  ,

  ruff check

  ,

  air format

  ,

  biome check

  , etc.
• Build:

  npm run build

  ,

  pip install -e .

  ,

  devtools::check()

  , etc.
• Type check:

  npm run check-types

  ,

  mypy

  ,

  pyright

  , etc.
• Tests:

  npm test

  ,

  pytest

  ,

  devtools::test()

  ,

  cargo test

  , etc.

• Obvious, mechanical fixes — fix autonomously:
  • Formatting issues (run auto-formatter if available)
  • Lint errors with clear fixes
  • Simple build, test, or type errors with obvious corrections
  • Stage the fixed files and commit the fix (specific files, not

    git add -A

    )
  • Re-run the failing check to confirm it passes
  • ALWAYS call out changes made in this step in the final summary
• Non-obvious failures — use

  AskUserQuestion

  to present the issue and offer resolution options

**IMPORTANT:** Do NOT run `gh run watch` without redirecting output. It generates thousands of lines of repeated status updates. Always redirect to `/dev/null` and rely on the exit code.

**Store run ID in task:**

• taskId: [ci task ID]
• metadata: {"runId": "[run-id]", "status": "running"}

undefined

TaskUpdate:
- taskId: [ci task ID]
- subject: "CI Run #[N]: passed"
- status: "completed"
- metadata: {"status": "passed"}

• STOP HERE - do not merge
• Report to user with PR URL, branch, and CI status

TaskUpdate:
- taskId: [ci task ID]
- subject: "CI Run #[N]: failed"
- status: "completed"
- metadata: {"status": "failed", "failureReason": "[brief reason]"}

1. Get failure details:

   --log-failed

   can produce thousands of lines. Use a targeted approach:
   bash

   # Summary of which jobs/steps failed
   gh run view <run-id>
   
   # Failed logs, limited to the last 40 lines (where the error usually is)
   gh run view <run-id> --log-failed 2>&1 | tail -40
   
   # Search for specific errors if needed
   gh run view <run-id> --log-failed 2>&1 | grep -A 5 -B 5 "error\|Error\|FAIL\|failed"

   Work from the bottom of the output upward — the actual error is almost always near the end.
2. Reproduce locally using the project's local check commands (discovered in Step 6).
3. Create a fix task:

   TaskCreate:
   - subject: "Fix: [failure reason]"
   - description: "Fixing CI failure from Run #[N]: [detailed error]"
   - activeForm: "Fixing [failure reason]"
   
   TaskUpdate:
   - taskId: [fix task ID]
   - addBlockedBy: [ci task ID]
   - status: "in_progress"

4. Fix the issue, verify locally, then commit and push:
   bash

   git add <specific-files>
   git commit -m "$(cat <<'EOF'
   fix: <what was fixed>
   EOF
   )"
   git push

5. Mark fix task completed:

   TaskUpdate:
   - taskId: [fix task ID]
   - status: "completed"

6. Return to Step 9 — monitor the new CI run (increment run number)

• Run #1: Failed (lint) -> Fixed in [hash]
• Run #2: Passed

undefined

1. NEVER merge the PR - only create it and ensure CI passes
2. NEVER force push unless explicitly asked
3. NEVER push to base branch directly
4. Continue fixing until CI passes - don't give up after one failure
5. Preserve commit history - don't squash unless asked
6. ALWAYS preview PR title and body with the user before creating
7. ALWAYS stage specific files - never use

   git add -A

   or

   git add .

8. NEVER amend commits unless explicitly asked - always create new commits for fixes