opencodekit 0.10.0 → 0.11.1

package/dist/template/.opencode/command/fix-ci.md

@@ -1,52 +1,325 @@
 ---
-description: Analyze Github Actions logs and fix issues with bead tracking
-argument-hint: "[github-actions-url]"
+description: Analyze GitHub Actions logs and fix issues with bead tracking
+argument-hint: "<github-actions-url or run-id>"
+agent: build
 ---
 
-**Load skill:** `skill({ name: "systematic-debugging" })`
+# Fix CI: $ARGUMENTS
 
-For deep tracing: `skill({ name: "root-cause-tracing" })`
+## Phase 1: Load Skills & Create Bead
 
-## Github Actions URL
+**Load skills:**
 
-<url>$ARGUMENTS</url>
-
-## Create Bug Bead
+```typescript
+skill({ name: "beads" }); // Session protocol
+skill({ name: "systematic-debugging" });
+skill({ name: "root-cause-tracing" });
+```
 
-CI failures are P0 bugs. Create a bead to track:
+**CI failures are P0 bugs.** Create bead immediately:
 
 ```typescript
 bd_add({
-  title: "Fix CI: <failure summary>",
-  type: "task",
+  title: "Fix CI: [failure summary]",
+  type: "bug",
   pri: 0,
-  tags: ["bug"],
+  tags: ["ci", "bug"],
+});
+```
+
+**Reserve workflow files:**
+
+```typescript
+bd_reserve({
+  paths: [".github/workflows/**", "package.json", "tsconfig.json"],
+  reason: "Fixing CI: $ARGUMENTS",
+  ttl: 600,
+});
+```
+
+## Phase 2: Fetch CI Logs
+
+**From URL:**
+
+```bash
+# Extract run ID from URL
+# https://github.com/owner/repo/actions/runs/12345678
+gh run view 12345678 --log-failed
+```
+
+**From run ID:**
+
+```bash
+gh run view $ARGUMENTS --log-failed
+```
+
+**List recent failed runs:**
+
+```bash
+gh run list --status=failure --limit=5
+```
+
+**Get full logs:**
+
+```bash
+gh run view $ARGUMENTS --log > /tmp/ci-log.txt
+```
+
+## Phase 3: Extract Errors
+
+Parse the CI log for errors:
+
+```bash
+# Find error lines
+grep -i "error\|failed\|exception" /tmp/ci-log.txt | head -30
+
+# Find the failing step
+gh run view $ARGUMENTS --json jobs --jq '.jobs[] | select(.conclusion=="failure") | {name, steps: [.steps[] | select(.conclusion=="failure")]}'
+```
+
+**Extract key information:**
+
+| Field             | Extract                        |
+| ----------------- | ------------------------------ |
+| **Failing job**   | Which job failed               |
+| **Failing step**  | Which step in the job          |
+| **Error message** | Exact error text               |
+| **Exit code**     | Process exit code if available |
+| **Context**       | Lines before/after error       |
+
+```
+CI Failure Analysis:
+━━━━━━━━━━━━━━━━━━━━
+
+Job: [job name]
+Step: [step name]
+Error: [error message]
+
+Context:
+[relevant log lines]
+```
+
+## Phase 4: Identify Failure Pattern
+
+Common CI failure patterns:
+
+| Pattern                  | Symptoms                           | Typical Fix                         |
+| ------------------------ | ---------------------------------- | ----------------------------------- |
+| **Dependency issue**     | "module not found", npm/yarn error | Update lockfile, check versions     |
+| **Environment mismatch** | Works locally, fails in CI         | Check Node/Python version, env vars |
+| **Test flakiness**       | Intermittent failures              | Add retries, fix race conditions    |
+| **Build timeout**        | Job cancelled after N minutes      | Optimize build, increase timeout    |
+| **Type error**           | TypeScript compilation failed      | Fix type errors locally first       |
+| **Lint error**           | ESLint/Prettier failures           | Run lint locally, fix issues        |
+| **Secret missing**       | "secret not found"                 | Check repository secrets config     |
+| **Permission denied**    | GITHUB_TOKEN issues                | Check workflow permissions          |
+| **Cache issue**          | Stale cache causing failures       | Clear cache, update cache key       |
+| **Docker issue**         | Image pull/build failures          | Check Dockerfile, registry auth     |
+
+## Phase 5: Estimate Complexity
+
+| Signals                             | Estimate | Approach           |
+| ----------------------------------- | -------- | ------------------ |
+| Single config change, obvious fix   | S (~10)  | Quick fix          |
+| Dependency update, env var fix      | M (~30)  | Systematic         |
+| Flaky tests, race conditions        | L (~100) | Deep investigation |
+| Workflow restructure, cross-cutting | XL       | Plan first         |
+
+## Phase 6: Reproduce Locally (if possible)
+
+Try to reproduce the failure locally:
+
+```bash
+# Run the same commands as CI
+npm ci
+npm run build
+npm test
+npm run lint
+```
+
+If it passes locally but fails in CI:
+
+```bash
+# Check for environment differences
+node --version    # Compare to CI
+npm --version     # Compare to CI
+cat .nvmrc        # If exists
+```
+
+## Phase 7: Fix
+
+**For complex fixes (≥3 phases):**
+
+```typescript
+task({
+  subagent_type: "planner",
+  description: "Plan CI fix",
+  prompt: "Create implementation plan for fixing CI: [failure description]",
+});
+```
+
+Save plan to `.beads/artifacts/<bead-id>/spec.md`
+
+**Common fixes:**
+
+```bash
+# Dependency issues
+rm -rf node_modules package-lock.json
+npm install
+
+# Type errors
+npm run type-check  # Fix locally first
+
+# Lint errors
+npm run lint -- --fix
+
+# Cache issues (add to workflow)
+# - uses: actions/cache@v3
+#   with:
+#     key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+```
+
+## Phase 8: Verify Locally
+
+Before pushing:
+
+```bash
+npm run build
+npm test
+npm run lint
+npm run type-check
+```
+
+All must pass locally.
+
+## Phase 9: Push & Re-trigger CI
+
+```bash
+git add <files>
+git commit -m "fix(ci): <description>
+
+Root cause: [what was wrong]
+<bead-id>"
+
+git push
+```
+
+**Re-trigger CI:**
+
+```bash
+gh workflow run <workflow-name>
+# or
+gh run rerun $ARGUMENTS --failed
+```
+
+**Watch CI status:**
+
+```bash
+gh run watch
+```
+
+```
+CI Verification:
+━━━━━━━━━━━━━━━━
+
+Run ID: [new run id]
+Status: [pending/success/failure]
+URL: [run url]
+```
+
+## Phase 10: Handle Results
+
+**If CI passes:**
+
+```typescript
+observation({
+  type: "bugfix",
+  title: "CI fix: [summary]",
+  content: `
+## Root Cause
+[What was actually wrong]
+
+## Fix
+[What we changed]
+
+## Prevention
+[How to avoid in future]
+  `,
+  concepts: "ci, github-actions, [specific issue]",
+  bead_id: "<bead-id>",
 });
+
+bd_done({ id: "<bead-id>", msg: "CI fixed: [summary]" });
 ```
 
-Save the bead ID for tracking. Add the CI run reference via `bd_msg` or notes.
+**If CI still fails:**
 
-## Workflow
+Iterate:
 
-1. **Analyze:** Use `build` agent to read the GitHub Actions logs, analyze and find the root causes of the issues.
+1. Fetch new logs
+2. Identify new/remaining error
+3. Fix and push again
+4. Maximum 3 iterations before escalating
 
-2. **Plan:** For complex CI/CD problems (≥3 phases), delegate to `planner` agent to create a detailed implementation plan. Save plan to `.beads/artifacts/<bead-id>/spec.md`.
+**If fix makes things worse:**
 
-3. **Fix:** Use `build` agent to implement the fixes step by step.
+```bash
+git revert HEAD
+git push
+```
 
-4. **Verify:** Use `review` agent to run tests, ensure quality and security, then report back.
+Then reassess approach.
 
-5. **Iterate:** If there are issues or failed tests, `build` agent will fix them and repeat the process until all tests pass.
+## Phase 11: Update Memory
 
-## Close Bead
+If this was a recurring CI issue:
 
-Once CI passes:
+```typescript
+memory -
+  update({
+    file: "project/gotchas",
+    content: `
+## CI: [Issue Title]
+
+**Symptom:** [What you see in CI logs]
+**Cause:** [Root cause]
+**Fix:** [How to resolve]
+**Prevention:** [Config to prevent recurrence]
+  `,
+    mode: "append",
+  });
+```
+
+## Phase 12: Sync & Report
 
 ```typescript
-bd_done({ id: "<bead-id>", msg: "CI fixed: <summary of fix>" });
+bd_release({ _: true });
+bd_sync({ reason: "Fixed CI: $ARGUMENTS" });
+```
+
+```
+CI Fixed: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━━
+
+Estimate: [S/M/L]
+Root cause: [brief description]
+Pattern: [which common pattern]
+
+Changes:
+- [file] - [change]
+
+CI Run: [new run URL]
+Status: Passed ✓
+
+Observation: Created ✓
+Gotcha: [Added/Not needed]
+
+Commit: [hash]
 ```
 
 ## Notes
 
-- If `gh` command is not available, instruct the user to install and authorize GitHub CLI first.
-- If the fix reveals systemic issues, create related beads for follow-up work.
+- If `gh` CLI is not available: `brew install gh && gh auth login`
+- If fix reveals systemic issues, create follow-up beads
+- For flaky tests, consider adding retry logic or fixing race conditions
+- Check if same failure happened before: `gh run list --status=failure --limit=20`