Fix Issues

fix-issues

This is the issue-ledger maintenance workflow. It should:

• fix all open issues by default
• organize them into coherent execution batches
• plan the work explicitly
• stop only when scope or behavior is not clear enough to proceed safely
• implement, audit, verify, and close each batch until all issues are resolved

Defaults

• Default mode is plan-first unless the surrounding request clearly includes execution and the selected issue batch is unambiguous.
• Default issue set is all open issues in ISSUES.md. Narrow the set only when the user explicitly specifies issue IDs, a count, or a scope limit.
• When the full set is large, organize issues into coherent execution batches (by shared area, shared prerequisites, or clean verification boundary) and work through all batches sequentially.
• Default file-touch budget is reviewable per batch, not exhaustive.
• Default verification depth is the fastest credible repo-defined check, escalating when risk warrants it.

Required artifacts

Use one shared run-id = YYYYMMDD-HHMMSS-.

Create:

• .agent-layer/tmp/fix-issues..report.md

Create files with touch before writing. Record delegated plan-work and multi-agent-plan-review artifact paths in the report as they appear.

Inputs

Accept any combination of:

• an issue count or explicit issue identifiers
• whether this run is plan-only or allowed to execute after readiness gating
• a verification depth preference
• a scope preference such as targeted or all-selected
• review_agents: one or more dispatch agent roles for multi-agent-plan-review

Fail before side effects unless review_agents is present. They may be terse (codex high, claude opus xhigh, antigravity). Infer the agent only when unambiguous.

Multi-agent pattern

Recommended roles:

1. Issue triage lead: selects the issue batch.
2. Planner: invokes plan-work for the selected issue batch.
3. Plan review agents: handled through multi-agent-plan-review.
4. Execution gatekeeper: decides whether the current batch should proceed, revise, escalate, or rewrite-because-out-of-scope.
5. Implementer: owns the code changes.
6. Auditor: reviews touched areas for regressions and missed fixes.
7. Verifier: runs the repo-defined checks.
8. Reporter: writes the final resolution report.

Context Discipline

You are the orchestrator. Do not do the child/subagent work yourself. Your job is to preserve your context to make strategic decisions, ensure each child skill or subagent follows its assigned contract, reconcile their outputs, enforce this workflow's gates, and continue the parent workflow after every child return.

Global constraints

• Keep scope to the selected issue batch plus directly blocking prerequisites.
• Do not invent missing issue details; treat ambiguous issues as blockers to clarify.
• Keep changes reviewable and aligned with repo conventions.
• Remove resolved issues from ISSUES.md; log newly discovered out-of-scope problems instead of silently expanding scope.
• If new evidence invalidates the plan, jump back to the earliest affected phase instead of continuing on stale assumptions.
• Treat readiness gating as an internal execution decision, not as a reason to ask the user unless a human checkpoint is actually triggered.

Human checkpoints

• Required: ask when fixing a selected issue would require a breaking change, broad architectural refactor, or materially larger scope.
• Required: ask when issue wording and repo evidence still leave the intended fix ambiguous after planning and gating.
• Stay autonomous while planning, gating, implementing, auditing, and verifying a clear issue batch.

Issue workflow

Phase 0: Preflight (Issue triage lead)

1. Confirm baseline with:

• git status --porcelain
• git diff --stat

1. Read, in order, when they exist:

• ISSUES.md
• ROADMAP.md
• DECISIONS.md
• COMMANDS.md
• README.md

Phase 1: Select and batch all issues (Issue triage lead)

1. If the user specified issue IDs or a count, use that as the issue set.
2. Otherwise select all open issues from ISSUES.md.
3. For each issue, decide whether it is actually an issue or a misplaced backlog feature:

• If an issue describes a new end-user-visible capability rather than a bug, defect, debt, or risk, move it to BACKLOG.md and remove it from ISSUES.md.
• Record every reclassification in the report.

1. Organize the remaining issue set into coherent execution batches by:

• shared area or module
• shared prerequisite work
• clean verification boundary

1. Order the batches so that prerequisite fixes land first.
2. State the full issue set, any reclassifications, the batch breakdown, and the execution order before proceeding.

Phase 2: Draft the plan and task list (Planner)

Use the plan-work skill for the current issue batch. Pass the selected issues, excluded issues, rollback or recovery notes, and parent report path; do not duplicate plan-work artifact instructions here.

Phase 3: Review the current issue batch plan (Plan review agents)

Use multi-agent-plan-review with:

• review_agents: the review agent dispatch roles
• the plan, task, and context artifact paths returned by plan-work

If final readiness is blocked-for-user-decision, ask the smallest question that unblocks the plan. Continue only when final readiness is implementation-ready.

Phase 4: Gate the current issue batch (Execution gatekeeper + Reporter)

After writing and reviewing the artifacts:

1. echo the plan, task, and context paths
2. summarize the selected issues, proposed approach, biggest risk, and verification plan
3. choose exactly one verdict:

• proceed (batch ready to implement): continue to Phase 5.
• revise (plan or task list needs updates): repeat from Phase 2.
• escalate (human checkpoint required): ask the smallest question that unblocks a trustworthy fix.
• rewrite-because-out-of-scope (batch too broad): rewrite to the largest still-in-scope subset, record deferred issues in the run artifacts/report, and return to the earliest affected phase.

Phase 5: Implement the current batch (Implementer)

1. Fix the selected issues in plan order.
2. For defect-oriented issues, write or identify a failing test that reproduces the defect before fixing it, when feasible. For pure debt or refactor issues, verify against existing checks instead.
3. Keep diffs narrow and explainable.
4. If a selected issue proves materially broader than planned, hand it back to the execution gatekeeper instead of freelancing.

If the touched scope accumulates obvious local complexity or dead scaffolding that can be fixed without broadening scope:

• use the simplify-new-code skill
• then continue to Phase 6

Phase 6: Audit the touched area (Auditor)

Review:

• whether each selected issue is actually resolved
• nearby regression risks
• standards alignment
• whether any new out-of-scope issue should be logged

Fix small in-scope follow-on problems immediately. Log larger out-of-scope problems instead of expanding the batch.

Phase 7: Verify and close the current batch (Verifier + Reporter)

1. Run the best repo-defined verification command for the selected risk level.
2. Remove resolved issues from ISSUES.md.
3. Add any genuinely new out-of-scope issue entries.
4. Update the report at .agent-layer/tmp/fix-issues..report.md with the batch results.

Phase 8: Advance to the next batch or close the run (Issue triage lead + Reporter)

If unprocessed batches remain:

1. Select the next batch from Phase 1's ordering.
2. Return to Phase 2 to plan the next batch.

If all batches are complete:

1. Finalize .agent-layer/tmp/fix-issues..report.md with:

• all issues fixed (by batch)
• issues reclassified and moved to BACKLOG.md
• issues deferred or rejected
• delegated plan-work and multi-agent-plan-review artifact paths
• verification performed
• remaining follow-up

When no broader orchestrator already owns closeout, use the finish-task skill here. If it reveals incomplete issue resolution or stale memory/docs, jump back to the earliest affected phase.

Guardrails

• Do not convert this into a general cleanup pass.
• Do not leave issue dispositions implicit.
• Do not weaken checks or lower thresholds to “finish” an issue batch.
• Do not close issues that were only partially addressed.
• Do not treat rewrite-because-out-of-scope as permission to silently drop selected issues; record the deferrals explicitly in the run artifacts/report, not in ISSUES.md.
• Do not stop after the first batch if unprocessed batches remain.

Definition of done

• The parent report exists at .agent-layer/tmp/fix-issues..report.md and lists every selected issue with a disposition of fixed, deferred, rejected, or reclassified.
• Every implemented batch used plan-work, and the returned plan/task/context artifacts went through multi-agent-plan-review and reached implementation-ready before the execution gate proceeded.
• Every resolved issue is removed from ISSUES.md; reclassified items moved to BACKLOG.md; newly discovered out-of-scope issues are logged as fresh ISSUES.md entries.
• Deferred selected issues are not annotated in ISSUES.md; they remain as open issues unless separately reclassified or resolved.
• The repo-defined verification command ran at least once per batch and its result is recorded in the report.
• The run processed every selected batch in order — no early stop with unprocessed batches, unless a human checkpoint blocked progress and the report names it.

Final handoff

After writing the report:

1. Echo the parent report path and delegated artifact paths.
2. Summarize the resolved issues and any deferred ones.
3. State the verification outcome clearly.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: conn-castle
• Source: conn-castle/agent-layer
• License: MIT
• Homepage: https://agent-layer.dev/

Install and usage instructions live in the source repository linked above.