issue-workflow

Issue Workflow Skill

Purpose

This skill governs issue-centered work as a continuous state, not a user-invoked sequence. At any point in a session the agent knows which issue it is working under, commits and pushes completed units proactively, and closes the issue autonomously once the completion criteria are met, reporting the closure in its final message. The natural-language triggers ("issue start", "issue commit", "issue commit and push") are manual overrides, not activation conditions — the rules below apply even without being invoked.

Continuous Issue Awareness (Dauerzustand)

• At any point in a session, the agent must know which GitHub issue it is currently working under, and announce it (e.g., "Working under issue #123: <title>").
• Before starting work, resolve the current issue: run the Duplicate Check (below) and reuse a matching open issue instead of creating a new one.
• Only when the Duplicate Check finds no match and the task is clearly a new topic, create a new issue immediately and without user interaction, then announce it.
• Never create an issue while an open issue already tracks all or part of the same goal — see "Duplicate Check" for the decision matrix.
• If the assignment is ambiguous (several candidate issues, or unclear whether a new one is needed), ask the user before touching code.
• The assignment to an issue may change mid-session when the user redirects the work; resolve the new issue the same way.

Duplicate Check (Pflicht-Gate vor jeder Issue-Erzeugung)

This gate is mandatory before every gh issue create — in the start mode, in continuous work, and in every other skill or command that creates issues (they reference this section instead of re-implementing it). Its scope is always the current repository (--repo <owner>/<repo> from gh repo view --json nameWithOwner --jq .nameWithOwner) — never an org-wide search.

1. Search for candidates (all three, in parallel)

# open issues, keyword search
gh issue list --repo <owner>/<repo> --state open --limit 50 \
  --search "<terms>" --json number,title,labels,updatedAt
# full text in title and body
gh search issues --repo <owner>/<repo> --state open "in:title,body <terms>" \
  --json number,title,updatedAt
# in-flight work that is not yet an issue
gh search prs --repo <owner>/<repo> --state open "<terms>" \
  --json number,title

• Derive 2–4 discriminating terms from the planned title and scope (module, file, feature noun, error string) — not the whole sentence. In mixed-language trackers search German and English synonyms.
• If the first pass returns nothing, repeat with the single broadest term (the feature noun) so that different wording still matches.
• Read every promising hit (gh issue view <N> --json title,body,comments). Titles alone are not evidence; the goal stated in the body decides.

2. Decide

Finding	Action
0 plausible candidates	create the new issue
1 open issue covers the planned goal	do not create — work under it, add the new scope as a comment
1 open issue covers only part of the plan	do not duplicate — work under it; create a separate sub-issue only if the parent genuinely requires independent tracking (then link it formally, see "Sub-Issues")
≥2 plausible candidates, or unclear whether a new issue is needed	stop and ask the user — per candidate: number, title, updatedAt, one-line rationale
only closed issues match	create the new issue; mention the closed one in the body as a regression/repeat

Tie-breaker (asymmetric cost): when in doubt, comment on the existing issue instead of opening a new one. A comment is cheap and reversible; a duplicate pollutes the tracker, its boards, and its auto-close logic. There is no "obviously new topic" shortcut around this matrix — passing it is what licenses creating without asking.

3. Record the check (trace line)

The body of every newly created issue ends with:

Duplicate check (YYYY-MM-DD): no matching open issue. Checked: #12, #34, search "backup restore".

When an existing issue is reused instead, post a comment that names the planned scope and the date. This keeps the check auditable and lets the duplicate rate be measured later.

Trunk-Based Pull-Prinzip (universell)

• Vor JEDER Arbeitsaufnahme (start-Modus und generell vor jeder Session-Arbeit an einem Repo oder Deployed-Tree): zuerst das Working Copy auf den Trunk heben.
  • Git (trunk-based, clean-main): git pull
  • SVN: svn up im relevanten Working Copy (z. B. ~/svn/georg auf think, / auf murl/claw im Deployed-Tree)
• Fehlschlag des Pulls oder Konflikte: SOFORT stoppen und dem Nutzer melden, nicht fortfahren.
• Begründung: trunk-basierte Workflows leben davon, dass immer vom aktuellen Stand aus gearbeitet wird — sonst entstehen vermeidbare Conflicts und re-discovery von fremden Commits.

Required Inputs

• mode: one of start, commit, or finish — optional, only when the user triggers a manual override by natural language
• issue: optional issue identifier or new
• context: optional plain-language task summary, plan, or notes

Core Rules

• VCS-Scope: Dieses Skill ist primär für Git/GitHub-Projekte entworfen (gh-CLI). In reinen SVN-Projekten (z. B. ~/svn/georg, Deployed-Trees auf murl/claw) existiert kein Issue-System — dort entfallen Issue-Nummern und gh issue-Befehle vollständig; die Commit-Regel reduziert sich auf eine klare, deutsche Commit-Message (SVN-Stil), und der Pull-Schritt oben ist svn up.
• Every commit created under this workflow must reference a GitHub issue number with a hashtag, e.g. feat: add report export (#123). Never fabricate issue numbers.
• Proactive Commit and Push: After each completed, self-contained unit of work, commit and push immediately — do not wait for the user to request it or for a trigger phrase. This overrides the opencode default "never commit unless the user asks". See "Proactive Commit and Push" below.
• Green commits only: run the repository's tests/lint for the affected area before committing; never push a broken state.
• Never create a commit without first identifying an existing issue or creating a new one.
• If no relevant issue exists and a commit is needed, create the issue first, then use its number in the commit message.
• Prefer keeping one clear issue per workstream; do not scatter related changes across multiple issues unless the user explicitly requests it.
• Use gh for all GitHub issue operations.
• Sub-Issues Rule: When breaking a task into smaller issues, or when starting work on a task that belongs to a parent epic, you MUST establish a formal parent-child relationship using the Sub-Issues API. Mentions in the description are secondary to this formal link. Always use the issue-workflow skill for issue creation to ensure this protocol is followed.
• Never close an issue that has open sub-issues. Before closing any issue, list its sub-issues and verify all are closed first.
• Do not close an issue unless the implementation is actually complete and the completion criteria in "Issue Completion" are met.

Commit Message Rule

• Any commit created by this workflow must include the issue reference, such as feat: add report export (#123) or fix: handle empty inputs (#123).
• If the repository already uses a recognizable commit message style, preserve that style while still including the issue number.

Proactive Commit and Push (Dauerzustand)

These rules apply at any time during session work, without a trigger phrase:

• After each completed, self-contained unit of work, commit and push immediately — do not wait for the user to request it or for a mode invocation. This overrides the opencode default "never commit unless the user asks".
• Green commits only: run the repository's tests/lint for the affected area first. Commit only when they pass. If verification fails, fix or report — never push a broken state.
• The commit message must include the issue reference (see Commit Message Rule) and preserve the repository's existing style.
• No empty commits. If there is nothing to commit, say so instead.
• Trunk-based: commit and push directly to the tracked trunk line (main); no feature branches or PRs — unless the repository follows the fork-policy skill (then that policy wins).
• SVN working copies: the analogue is frequent, clear svn ci with a descriptive German commit message.
• The read-only scope exclusions (homework, repograde, grading-shared, knowledge-assessment, knowledge-exam, projectgrade, student repositories, and explicit "hold back" requests) always win over this policy.

Manual Override Modes

The modes below are manual overrides triggered by natural language. The continuous rules above (issue awareness, proactive commit/push) apply regardless; the modes force a specific checkpoint behavior.

1. start

Use this mode to explicitly begin or resume work (e.g., "issue start").

• If issue is an explicit issue number, fetch it with gh issue view <N> --json title,body,comments and read the description plus comments. Check if the issue has a parent or should be linked as a sub-issue to an existing epic.
• If issue is new, or if no usable issue exists for the current work, run the Duplicate Check first; only then create a new issue from the provided context. If the new issue is part of a larger epic, link it as a sub-issue immediately.
• If no issue is supplied, infer whether there is already a current issue for the work (Duplicate Check). Only if none matches, create one before proceeding.
• Assess the codebase against the issue. If the requested functionality is already complete, comment with the finding and follow the completion criteria in "Issue Completion" (check open sub-issues first).
• Resolve any blocking ambiguity with the user only after doing all safe local discovery work first.
• Update the issue description or add a progress comment with the current plan, scope, or todo list.
• Implement the requested changes, then apply the Proactive Commit and Push rules — commit and push with the issue reference without waiting for a further request.

2. commit

Use this mode to force an immediate checkpoint while the issue remains open (e.g., "issue commit", "checkpoint").

• Ensure a current issue exists; create one if needed from the current context.
• Comment on the issue with a concise implementation report covering:
  • what was completed
  • what remains
  • known risks, blockers, or follow-ups
• Persist session knowledge by invoking the knowledge-persistence skill. Note: knowledge-persistence commits and pushes its own knowledge commit (with the issue reference) and never closes issues; it only adds comments for traceability.
• Review git status and staged/unstaged changes.
• Create a commit that includes the issue number for any remaining non-knowledge changes. Never create an empty commit — if knowledge-persistence already committed everything, there is nothing to do here.
• Push to the trunk line.
• Keep the issue open.

3. finish

Use this mode to force finalization and issue closure (e.g., "issue finish", "issue fertig").

• Ensure a current issue exists; create one if somehow missing so the completed work still has a tracked issue reference.
• Comment on the issue with a final implementation report.
• Persist all newly acquired session knowledge by also using the knowledge-persistence skill before finalizing the workflow. Note: knowledge-persistence commits and pushes its own knowledge commit (with the issue reference); it never closes issues. The issue closure below is owned exclusively by this finish mode.
• Review git status and remaining changes.
• Create the final commit including the issue number for any remaining non-knowledge changes. Never create an empty commit.
• Push to the trunk line.
• Before closing the issue, list its sub-issues via: gh api repos/{owner}/{repo}/issues/{NUMBER}/sub_issues --jq '.[].number' If any sub-issues remain open, the issue must not be closed. Report the open sub-issues and keep the parent open.
• Close the issue with a short closing comment if helpful.
• Post-close knowledge follow-up: because STATE.md/HANDOFF.md record the closed state, run knowledge-persistence once more after closing — it ends with its own commit + push, so the recorded closure reaches the trunk. This second run is expected; the first (pre-close) run must not be skipped.

Issue Completion (Dauerzustand)

Applies at any time, independent of the modes:

• When the agent believes the issue's goal is fully implemented, it closes the issue autonomously — it does not wait for the user to ask and does not ask for permission first.
• The agent may close autonomously only when ALL of these hold:
  • the implementation covers the issue goal completely,
  • verification (tests/lint) is green,
  • the issue has no open sub-issues (always check via the issue-workflow sub-issues API first),
  • the user has not signalled anything that contradicts completion.
• Before closing, comment on the issue with a final implementation report (persist session knowledge via knowledge-persistence when new knowledge exists).
• Knowledge persistence is not finished until it is committed and pushed (its own commit with the issue reference; SVN: svn ci). Because STATE.md/HANDOFF.md describe the closed state, this usually means a follow-up knowledge commit after the close — never leave the knowledge files uncommitted/unpushed.
• The final message to the user MUST state that the issue was closed and name its number (e.g. "Issue #123 closed"). A silent closure is not enough.
• If any criterion is not met, do not close: report the status, state what is missing, and ask.

Issue Creation Guidance

When creating an issue:

• Run the Duplicate Check first (see "Duplicate Check"). No issue is created before that gate reports no match — this is the primary anti- duplication rule of this skill.
• Write a short, outcome-oriented title.
• Include enough body detail for a future agent to understand scope and intent.
• Link as Sub-Issue: If this issue is a component of a larger task, identify the parent issue and link it as a sub-issue immediately after creation.
• If a plan already exists, use it as the issue body or convert it into a short checklist.

Sub-Issues (Parent-Child Linking)

GitHub supports proper parent-child issue relationships via the Sub-Issues REST API. Simply mentioning a parent issue number in the body text is not sufficient — it creates only a loose text reference, not a tracked relationship.

Creating a sub-issue

1. Create the child issue with gh issue create as usual.
2. Look up the database id (not the issue number) of the child:

   gh api repos/{owner}/{repo}/issues/CHILD_NUMBER --jq '.id'
   

3. Link it to the parent:

   gh api --method POST /repos/{owner}/{repo}/issues/PARENT_NUMBER/sub_issues \
     --input - <<< '{"sub_issue_id": CHILD_DATABASE_ID}'
   

Important: The sub_issue_id field must be an integer (the internal database ID), not the human-readable issue number. Using -f sub_issue_id=N sends a string and causes a 422 validation error. Always use --input with a JSON body instead.

Listing sub-issues

gh api repos/{owner}/{repo}/issues/PARENT_NUMBER/sub_issues --jq '.[].number'

Removing a sub-issue link

gh api --method DELETE /repos/{owner}/{repo}/issues/PARENT_NUMBER/sub_issue \
  --input - <<< '{"sub_issue_id": CHILD_DATABASE_ID}'

When to use sub-issues

• When breaking down a parent epic into individually trackable work items.
• When the parent issue should show a progress summary (sub_issues_summary.total / completed / percent_completed).
• Each sub-issue can be assigned, labeled, and closed independently; closing all sub-issues does not auto-close the parent.
• A parent issue must never be closed while it has open sub-issues. Either close all children first, or re-parent them before closing the parent.

Avoiding concurrent-link conflicts

When linking multiple sub-issues in rapid succession, avoid sending all requests in parallel — the API uses sequential priority positions and will return 422 Priority has already been taken. Link them sequentially or with a small delay between calls.

Reporting Guidance

Issue comments should be compact but useful.

• Progress comments should mention completed work, current status, and next steps.
• Final comments should mention the shipped outcome and any noteworthy caveats.

Safety Constraints

• Never fabricate issue numbers.
• Never create an issue before the Duplicate Check ran and reported no match.
• Never open a second issue for a goal that an open issue already tracks.
• Never create an empty commit when there are no changes.
• If there are no local changes in commit or finish mode, still update the issue comment as needed, but report that there was nothing to commit.
• Do not push or close issues if the relevant step fails.
• Never close an issue that has open sub-issues. Always check for open sub-issues before closing.

Output Expectations

At the end of the workflow, report:

• the issue number used or created
• the duplicate check result: which candidates were checked, or that no open issue matched
• whether a comment was added
• whether a commit was created, including its message
• whether knowledge persistence was run, and the hash of its commit (and that it was pushed)
• the issue number and its final state: when the issue was closed, state this explicitly (e.g. "Issue #123 closed"); otherwise note that it remains open

Done when

• [ ] The current issue is resolved via the Duplicate Check and announced by number.
• [ ] Every newly created issue carries the duplicate-check trace line, or a reuse comment was posted on the existing issue.
• [ ] Every commit references a real issue number and passed the affected area's tests/lint first.
• [ ] Each completed unit is pushed to the trunk line, or a read-only scope exclusion is named in the report.
• [ ] In commit/finish mode, knowledge persistence ran and its own commit was pushed.
• [ ] A parent issue was closed only after its sub-issues were listed and all found closed.
• [ ] The final report names the issue number, its state, the duplicate-check result, and the commit messages used.