issue-workflow-guardrail

Issue Workflow Guardrail

Use this skill whenever the task is centered on a GitHub issue in this repository.

Examples:

• the user gives an issue number or URL
• the issue is still raw and needs shaping before coding
• the user asks to complete, triage, refine, or close an issue
• the issue is large enough to need parent/child split or schedule management
• multiple worker results must be rolled back into a mother issue
• the issue may be blocked, underspecified, or waiting on clarification
• the issue may have been opened by the user or by someone else

Do not run a one-time cleanup pass over old issues. Normalize an issue only when it becomes active.

For medium/large issue work, treat docs/general/issue-orchestration-workflow.md as the durable process baseline and use this skill as the operational entrypoint.

If repo-root .codex/private/issue-orchestration-private.md exists, read it after the public workflow doc and treat it as a local-only augmentation layer for orchestration heuristics, split quality, resume discipline, and product-decision timing. Do not assume that file exists in other clones.

Orchestration Model

Use this skill as the repository's main issue orchestrator:

• external reporter issue
  • preserve the reporter-owned body as the public communication record
  • before normalization or execution, create a new internal execution issue linked back to the external issue
  • use the internal issue as the workflow-managed unit for shaping, staged plans, snapshots, and close-out
  • if more splitting is needed later, split under the internal issue instead of rewriting the reporter-owned issue into a parent scheduler
• raw issue
  • shape the issue into a stable problem statement
  • decide whether it only has research closure or is ready for execution closure
• parent issue
  • hold the overall goal, schedule table, dependency order, and roll-up status
  • prefer this mode when one issue would otherwise mix multiple goals or validation surfaces
• child issue
  • treat as the default worker unit
  • do not hand it to implementation until it is an execution closure or a stable closure index
• unsplit direct-execution unit
  • when an issue stays unsplit, the active issue itself becomes the current worker unit
  • direct execution is not a bypass; it inherits the same worker-boundary, snapshot, product-gate, and verifier-decision rules
• execution snapshot
  • keep a durable current execution point and resume contract in the issue body or linked design doc
• product decision gate
  • when execution reaches a real product tradeoff, stop automation and hand back a minimal decision packet instead of guessing
• verifier handoff
  • when a medium/large issue is effectively complete, hand it to $issue-verifier for an independent read-only pass before close-out

Prefer these closure levels:

• research closure
  • enough information to decide whether to proceed, split, or keep investigating
• execution closure
  • enough information for a worker to implement without rebuilding wide context

If the active issue only reaches research closure, do not force direct implementation. Shape, split, or stop with the issue state updated.

External Reporter Flow

When the active GitHub issue was opened by someone else and still acts as the public bug report or feature request:

1. do not rewrite the original reporter-owned body into the internal workflow format
2. create a new internal execution issue first
3. link the two issues both ways
4. put all workflow structure on the internal issue:
   • background / goal / acceptance
   • execution decision
   • staged plan
   • execution snapshot
   • implementation / check / finish context
5. use the original external issue only for clarification, evidence requests, and final result comments
6. close the internal execution issue when its close gates pass
7. do not auto-close the original external issue; leave a concise completion comment there instead

Split and Roll-up Rules

Split before coding when any of these are true:

• the issue mixes multiple weakly related goals
• the required background is no longer a single coherent closure
• different parts need substantially different validation surfaces
• the work is naturally parallelizable

If you decide not to split, treat the active issue as the current worker unit and record that decision durably before coding.

For a parent issue, keep the body or a linked design doc current with:

• split structure
• recommended order
• dependency edges
• parallel groups
• current closure level for each unit
• next recommended ready unit

Roll results back into the parent issue whenever:

• a worker finishes a child issue
• a child issue changes the expected next stages
• new findings invalidate the previous split or dependency assumptions

Do not leave stage changes only in chat when they materially affect later execution.

Execution Decision Record

After prepare succeeds and before coding starts, write or refresh an execution decision record.

This record must say at least:

• whether the issue is being split
• if not split, why the active issue can safely act as a single worker unit
• what the current worker unit is
• whether an independent verifier pass is expected before close-out
• if verifier is not planned, why skipping it is acceptable for this run

Put this record in the active issue body, the parent issue, or a linked design doc. Do not leave it only in chat.

Durable Execution Snapshot

Do not rely on live chat context as the only execution memory.

For medium/large issue work, maintain a durable execution snapshot in the active parent issue, child issue, or its linked design doc.

The snapshot should contain at least:

• current stage
• current execution point
• done
• next step
• current blocker
• recently changed assumptions
• last known-good consistent state
• unfinished tail work
• resume steps

Update the snapshot at least:

• at the end of every stage
• before any normal stop path
• before handing work to another worker
• after a red inconsistency
• before and after a product decision gate

On resume, never continue from memory alone. Re-read the snapshot, linked closure material, and current code, then confirm the recorded next step is still valid. If not, refresh the snapshot first and only then continue.

For an unsplit direct-execution unit, a recorded stage or phase is execution sequencing only, not a default stopping point. When a stage ends, immediately decide among exactly these outcomes:

• the overall issue is actually complete
• a real blocker / contradiction / product decision gate now prevents safe continuation
• the issue must be formally split before more implementation
• continue directly into the next stage

Do not stop merely because phase A or another recorded stage finished.

Worker Boundary

Workers include both child issues and an unsplit active issue doing direct execution.

Workers own execution inside the current issue closure, not replanning outside it.

Use this practical rule:

• green inconsistency
  • fix locally when goals, acceptance, dependencies, and sibling assumptions stay unchanged
• yellow inconsistency
  • do one bounded investigation
  • continue only if the result still stays inside the current closure
• red inconsistency
  • stop local implementation
  • update the issue with the contradiction
  • return control to the orchestrating issue instead of repeatedly hacking through a broken assumption

Common red signals:

• goal or acceptance would need to change
• dependency order would need to change
• sibling issue assumptions are now invalid
• the issue no longer forms a stable execution closure
• the unsplit active issue no longer forms a stable single-worker closure

Product Decision Gate

Not every red inconsistency is purely technical.

When execution hits a real product decision, do not keep pushing by guessing product intent.

Treat it as a decision gate when any of these are true:

• user-visible semantics would change depending on the choice
• interaction or UX tradeoffs now matter to acceptance
• a technical limitation forces a product compromise
• multiple choices are implementable, but only product intent can decide the right one

At a decision gate:

1. stop autonomous implementation
2. update the active parent issue or current issue with a dedicated 待决策 or 产品待拍板 section
3. compress the problem into a minimal decision packet
4. ask only for the decision that is actually needed
5. after the user answers, sync the chosen direction back into the issue body before resuming work

The minimal decision packet should contain:

• trigger
• current constraint or evidence
• mutually exclusive options
• impact of each option
• recommended option
• exact decision needed
• affected child issues, stages, or validation surfaces

Do not dump the whole project context back onto the user. The goal is to ask the smallest question that safely unblocks the workflow.

Verifier Hook

Use $issue-verifier when:

• implementation is done or nearly done
• acceptance looks satisfied
• you want an independent pass before closure

The verifier pass is a role boundary, not just a longer self-review. Default to read-only verification unless the user explicitly asks for fixes as part of the same step. Even when the decision is “no verifier for this run”, make that an explicit recorded decision before close-out. Direct execution is not exempt.

Workflow Modes

full remains the default and keeps the existing workflow behavior unchanged.

fast is an explicit opt-in shortcut for already-clear, single-stage, low-risk issue work.

Treat these user phrases as a forced mode override:

• force fast
  • workflow:fast
  • fast path
  • 快速处理
  • 简化流程
• force full
  • workflow:full
  • full path
  • 完整流程
  • 标准 issue workflow

If the user does not force fast, keep using the unch

---

Content truncated.