| name | fix-issues |
| description | Triage and fix a batch of issues from GitHub or tracker files, with reproduction, prioritization, verification, reporting, and tracker updates. |
Codex Runtime Rules
These Z Skills are native Codex workflows derived from github.com/zeveck/zskills at commit 14dea81da487b2904ea7d69a27295f1869206cdf. They are invoked by natural language or by naming the skill; examples that look like slash commands are only shorthand for the skill name.
Use Codex behavior first:
- Read the current repository before acting. Prefer existing project scripts, config, and conventions over the upstream examples.
- Never use Claude-only tools or assumptions: no
CronCreate, CronList, CronDelete, Agent/Task tool syntax, allowed-tools, .claude/settings.json, or automatic Claude hooks.
- Use sub-agents only when the user explicitly asks for agents, parallel work, or delegation. For Z Skills landing gates, prefer a fresh independent verification context when it is available without violating the current Codex delegation policy; otherwise run inline, disclose lower assurance, and do not auto-land unless the user accepts it.
- For isolation, create git worktrees explicitly with normal
git worktree commands. Do not rely on an isolation: "worktree" parameter.
- Config lookup order is project
.agents/zskills-config.json first, then project zskills-config.json, then legacy .codex/zskills-config.json, then legacy .claude/zskills-config.json only if already present. Do not create new .claude runtime config for Codex.
- Scheduling is not automatic in Codex. If the user asks for recurring runs, explain the schedule and ask before installing any local cron/system scheduler. For normal turns, perform the requested work now.
- Helper assets live at project
.agents/zskills-support by default. Use project-local scripts/* first; fall back to $CODEX_HOME/zskills-support only for explicit global installs or legacy setups.
- Preserve Codex safety rules: do not revert unrelated work, stage files by name, avoid destructive git commands, and verify from actual diffs/tests.
Detailed upstream text is archived in references/upstream-claude-adapted.md for edge cases and future diffs. Load it only when the concise workflow below is insufficient.
Fix Issues
Workflow
- Determine mode: sprint (
N issues), sync, or plan.
- Discover issue sources: GitHub issues via
gh, repo trackers like plans/*ISSUES*.md, failing tests, or user-provided lists.
- Prioritize by severity, reproducibility, dependency order, and requested focus.
- For each selected issue, reproduce or prove the bug before editing. Skip issues that are too vague, too large, or blocked; document why.
- Fix in sprint-safe batches. For sprint mode, use isolated worktrees for cherry-pick or PR landing unless
direct was explicitly selected and allowed. Keep one issue or tightly grouped root cause per commit.
- Verify each fix with targeted tests and, when allowed by the current Codex delegation policy, a fresh verifier for the issue or batch before landing. Otherwise run inline verification and disclose the lower assurance.
- Append
SPRINT_REPORT.md before landing. Sprint mode does not close GitHub issues, finalize tracker state, or remove worktrees; fix-report owns those decisions.
Landing Modes
Resolve landing mode from explicit request first, then .agents/zskills-config.json, zskills-config.json, legacy .codex/zskills-config.json, legacy .claude/zskills-config.json, and finally cherry-pick.
direct: fix issues in the current tree only with a clean tree, no unrelated changes, and main not protected unless the user explicitly accepts the risk in the current turn.cherry-pick: fix each issue or small batch in a manual worktree, verify, write SPRINT_REPORT.md, then cherry-pick scoped commits back to ${execution.base_branch:-main}.pr / locked-main-pr: create one branch/PR per issue or grouped root cause using fix/issue-NNN naming when an issue number exists. Push to ${execution.remote:-origin}. Do not reuse the general plan branch prefix for sprint issue branches. Never push directly to main.
Automation Limits
auto means proceed through obvious internal gates in this turn; it does not authorize unsafe git operations, force pushes, or unattended local schedulers.
Tracking And Gates
Retain sprint tracking as active files:
- Create
.zskills/tracking/fix-issues.<sprint-id>/ at sprint start and write pipeline.fix-issues.<sprint-id>.
- Write sprint markers
step.fix-issues.<sprint-id>.preflight, .prioritize, .execute, .verify, .report, and .land.
- Write per-issue markers
issue.<issue-id>.selected, .reproduced or .skipped, .fixed, .verified, .landed, and .reported.
- Before verification, write
requires.verify-changes.<sprint-id> and require the verifier to produce fulfilled.verify-changes.<sprint-id>.
- Write
SPRINT_REPORT.md before landing or closing issues. Treat missing verification/report markers as a stop condition for auto-landing.
Run project-local scripts/zskills-gate.sh, .agents/zskills-support/scripts/zskills-gate.sh, or $CODEX_HOME/zskills-support/scripts/zskills-gate.sh before sprint landing when available.
Preserved Z Skills Invariants
sync is interactive before closing or mutating remote issues.- Read each issue body and tracker research before fixing; titles alone are not a spec.
- Skipped issues need explicit reasons.
- Write a sprint report before any landing/closure decisions.
- Preserve requested landing mode:
pr, direct, or cherry-pick-style local landing.
- Preserve file tracking gates for sprint state and landing readiness.
