Gitea-Tools/skills/llm-project-workflow/workflows/create-issue.md

---
task_mode: create-issue
canonical: true
final_report_schema: ../schemas/create-issue-final-report.md
---

# Create issue workflow (canonical)

**Task mode:** `create-issue`

This file is the canonical issue-creation workflow for Gitea-Tools. Load it
before any issue mutation. Final report schema:
[`schemas/create-issue-final-report.md`](../schemas/create-issue-final-report.md).

**BLOCKED + DIAGNOSE (universal default):** If at any point you cannot perform a required step (skill not available, terminal broken, capability missing, wrong profile, guard blocks, worktree misbound, instructions unavailable, preflight fails, etc.), STOP. Clearly state BLOCKED. Use the standard [`../templates/blocked-diagnose-report.md`](../templates/blocked-diagnose-report.md) template. Only safe non-mutating recovery. Report using the template. Do not continue or use any fallback (temp scripts, direct API, etc.) unless controller authorizes. All blocker classes listed in llm-project-workflow/SKILL.md must trigger this.

**Default task prompt:**

> Create or update Gitea issues in this project only if every identity,
> capability, duplicate-search, issue-scope, final-report, mutation-ledger,
> and proof-wording gate passes.

Do not improvise around the gates. Follow project skills, MCP gates, and
workflow rules exactly.

This is an issue-creation workflow. It is not a reviewer workflow and not an
implementation workflow.

---

## 0. Load the canonical workflow first

Before starting issue creation or issue update work, check whether the project provides a canonical create-issue workflow through a project skill, runbook, or MCP helper.

If available, load it first and report:

* workflow source
* workflow version, commit, or hash
* whether this prompt conflicts with the loaded workflow

If the canonical workflow cannot be loaded and the project requires it, stop and produce a recovery handoff only.

## 1. Mode isolation

This run is `create-issue` mode only.

Do not:

* review PRs
* approve PRs
* request changes
* merge PRs
* close PRs
* close issues unless the user explicitly asks and exact close capability is proven
* implement code
* edit repo files
* create branches
* create commits
* push branches
* create PRs
* run tests unless the canonical workflow explicitly requires validation for issue creation
* perform reviewer-only actions
* perform author/coder-only actions
* perform MCP repair

If the task requires review, merge, issue implementation, or MCP repair mode, stop and produce a handoff for the correct workflow.

Do not mix modes in one run.

## 2. Start with live identity, profile, runtime, and capability checks

Prove:

* authenticated identity
* active profile
* repo/project
* runtime context
* exact capability for reading/searching issues
* exact capability for creating issues, if creating issues
* exact capability for commenting on issues, if commenting on existing issues
* exact capability for editing issues, if editing existing issues
* exact capability for applying labels, if applying labels
* exact capability for assigning issues, if assigning issues
* exact capability for closing issues, only if explicitly requested

A nearby capability does not count.

Examples:

* `create_issue` does not authorize `issue_comment`
* `issue_comment` does not authorize `create_issue`
* `create_pr` does not authorize `create_issue`
* `review_pr` does not authorize `create_issue`
* `merge_pr` does not authorize `issue_comment`
* `gitea.read` does not authorize creating, commenting, editing, labeling, assigning, or closing issues

If exact capability cannot be proven, stop and produce a recovery handoff only.

## 3. Stop immediately on blocked infrastructure

If any of the following appears, stop immediately:

* `infra_stop`
* MCP reconnect failure
* stale capability state
* missing capability
* workspace mismatch
* dirty control checkout, if the canonical workflow treats that as blocking
* broken canonical workflow loading
* failed required preflight
* capability resolver warning that says the current state may be unsafe
* stale or inconsistent runtime context

Do not continue duplicate search, issue creation, issue commenting, issue editing, labeling, assignment, or cleanup.

Produce an executable recovery handoff only.

Blocked recovery handoffs must not include direct issue-create or issue-comment replay commands.

Blocked handoffs must say to rerun the full workflow after the blocker clears.

## 4. Main checkout rule

This workflow should not mutate repo files.

Do not edit files in the main checkout.

Do not create branches.

Do not create commits.

Do not push.

Do not run implementation work.

Do not run reviewer validation.

Reading repository files is allowed only when needed to understand the requested issue and only if the canonical workflow permits it.

If the main checkout is dirty and the project treats dirty control checkout as blocking, stop and produce a recovery handoff.

## 5. No raw MCP repair during issue creation

Do not run `pkill`, kill MCP processes, edit MCP config, restart servers, or perform control-checkout repair during issue creation.

If MCP repair is required, stop issue creation and produce a separate `CONTROL-CHECKOUT REPAIR MODE` handoff.

Do not mix MCP repair mode with create-issue mode.

After repair, rerun the full workflow from the beginning.

## 6. No background task tools

Do not use `schedule`, `manage_task`, background jobs, async waits, delayed task tools, or monitoring tasks during issue creation.

Use direct commands and MCP tools only.

If a required action cannot complete synchronously, stop and produce a recovery handoff.

Do not say “I will check later,” “I will monitor,” or “I will continue in the background.”

## 7. No local Gitea fallback during normal issue creation

During normal issue-creation workflows, do not read Gitea profile secret files.

Do not inspect or open files such as:

* `profiles.json`
* local token stores
* credential files
* local Gitea auth/profile config files
* `.env` files containing Gitea credentials
* keychain dumps
* token helper outputs

Do not run local Gitea helper scripts when MCP tools are available.

Use MCP tools for Gitea operations.

Local fallback is allowed only in explicit recovery mode when MCP is unavailable and identity/profile/capability can be independently proven.

If local fallback is used, report:

* why MCP was unavailable
* exact identity proof
* exact profile proof
* exact repo proof
* exact capability proof
* exact local command used

Do not use local fallback to bypass MCP gates.

## 8. Understand the requested issue work

Before searching or creating issues, restate the requested issue-creation task in operational terms.

Identify:

* target repo/project
* issue topic
* issue type, if known
* whether this is a new issue, duplicate check, issue update, or issue-comment task
* whether the user provided exact title/body text
* whether acceptance criteria were provided
* whether multiple issues are requested
* whether labels, assignees, milestones, or links are requested
* whether any requested action requires capability beyond issue creation

Do not invent missing requirements.

If the request is ambiguous but safe to proceed, make a reasonable best-effort issue with clear assumptions.

If ambiguity would cause unsafe or wrong mutation, stop and ask for clarification or produce a recovery handoff according to project policy.

## 9. Duplicate search before mutation

Before creating any issue, search open and closed issues for duplicates.

Duplicate search must happen before each issue creation unless a batch search clearly covers all proposed issues.

Search terms must include:

* exact proposed issue title
* key noun phrase from the problem
* key workflow/tool name
* key failure phrase or error phrase
* likely alternate wording
* linked PR number, issue number, or file name, if relevant

If the user supplied search terms, use those too.

For each proposed issue, report:

* search terms used
* matching issue numbers/titles
* whether each match is open or closed
* whether any match fully covers the requested issue
* whether any match partially covers the requested issue
* whether a new issue is still needed

Do not create a duplicate issue if an existing issue fully covers the problem.

If a duplicate exists and fully covers the problem, stop issue creation for that topic and report the duplicate.

If a duplicate exists but is missing important acceptance criteria, comment on the existing issue only if exact `issue_comment` capability is proven and the user/task authorizes commenting.

If commenting is not authorized, report the existing issue and the missing criteria in the final handoff.

## 10. Issue inventory pagination rule

If listing/searching issues returns paginated results, follow pagination until the tool proves there are no more pages.

Do not assume search results or issue inventory are complete.

Pagination proof must not rely on assumed default API page size.

Search/inventory is complete only if one of the following is proven:

* the MCP response explicitly says there is no next page / `has_more=false` / final page
* the workflow traversed pages until an empty page or explicit final page was returned
* the tool response includes total-count or pagination metadata proving all relevant issues were returned
* the request explicitly set `page` / `limit` / `per_page`, and the response explicitly proves the server honored that page size and did not truncate results

Do not say “duplicate search complete” merely because the result count is less than an assumed default page size.

If pagination metadata is absent and the tool cannot page, report `ISSUE_SEARCH_PAGINATION_UNPROVEN`.

If duplicate search cannot be trusted, do not create the issue unless the canonical workflow explicitly permits best-effort issue creation with that limitation disclosed.

## 11. Issue creation scope rule

Create only issues within the requested scope.

Do not create extra issues just because related problems are noticed.

Do not create process-hardening issues unless the user explicitly requested process-hardening or the current task is explicitly about workflow/tooling gaps.

Do not create implementation issues during reviewer mode.

Do not create reviewer issues during work-on-issue mode.

Do not create issues in a different repository unless the user explicitly asked and exact capability is proven.

If multiple issues are requested, create only the requested issues and only after duplicate search for each one.

If a proposed issue is too broad, split it only if the user requested splitting or the canonical workflow requires issue granularity.

## 12. Issue content quality rule

Every created issue must be actionable.

Include, when applicable:

* title
* problem statement
* observed evidence
* expected behavior
* required behavior
* acceptance criteria
* affected workflow/tool/files
* safety or security considerations
* duplicate search summary
* related issues or PRs
* non-goals, if useful

Acceptance criteria must be concrete and testable.

Avoid vague issues like:

* “make workflow better”
* “fix LLM behavior”
* “improve process”
* “handle this better”

Instead, describe the exact wall, gate, verifier, test, schema, helper, or prompt change required.

## 13. Issue title rule

Use concise, specific titles.

Good title patterns:

* `Enforce <specific gate>`
* `Add verifier for <specific report/proof problem>`
* `Split <large workflow> into <specific components>`
* `Block <unsafe action> during <workflow mode>`
* `Require <proof type> before <claim/action>`

Avoid titles that are too broad or emotional.

The title should be unique enough that duplicate search can find it later.

## 14. Issue body rule

Issue body must include the full acceptance criteria.

Do not create placeholder issues.

Do not create issues with only a title unless the user explicitly requested title-only creation.

If the user supplied exact issue body text, preserve it unless it contains unsafe instructions, stale facts, or contradictions.

If edits are needed, make the smallest correction necessary and report the correction.

Do not silently change requested meaning.

## 15. Labels, assignees, and metadata

Apply labels, assignees, milestones, or project fields only if:

* the user requested them, or
* the canonical workflow requires them, and
* exact capability is proven.

Do not guess labels if project label policy is unknown.

If labels are useful but capability or policy is unclear, mention recommended labels in the final report instead of applying them.

Do not assign issues to people unless explicitly requested or required by project workflow.

## 16. Comment-on-existing issue rule

Comment on an existing issue only if:

* an existing issue partially covers the requested work, or
* the user asked to add information to an existing issue, or
* the canonical workflow requires duplicate consolidation comments, and
* exact `issue_comment` capability is proven.

Comment must be specific and useful.

Include:

* why the existing issue is relevant
* what acceptance criteria or evidence should be added
* whether this avoids creating a duplicate

Do not comment just to say “duplicate found” unless the project workflow requires it.

Do not close duplicate issues unless explicitly requested and exact close capability is proven.

## 17. No hidden mutations

Do not perform unreported mutations.

Every issue creation, issue comment, issue edit, label change, assignment, milestone change, close/reopen action, or external-state change must be reported.

If a tool call is dry-run-only, confirmation-gated, rejected, or no-op, report it separately from performed mutations.

A dry run is not a mutation.

A rejected call is not a performed mutation.

A successful issue creation is an issue mutation.

A successful issue comment is an issue mutation.

A successful label/assignment/milestone update is an issue mutation or external-state mutation.

## 18. Issue creation gate

Before creating each issue, verify:

* identity is still valid
* active profile is still valid
* runtime context is still safe
* exact `create_issue` capability is still valid
* duplicate search was completed or limitation was explicitly allowed
* proposed title is not a duplicate
* proposed body includes actionable acceptance criteria
* target repo is correct
* no mode switch has occurred

If any gate fails, do not create the issue.

Produce a recovery handoff or duplicate report.

## 19. Issue commenting gate

Before commenting on an existing issue, verify:

* identity is still valid
* active profile is still valid
* runtime context is still safe
* exact `issue_comment` capability is still valid
* target issue number is correct
* comment body is specific and useful
* comment will not duplicate an existing comment
* no mode switch has occurred

If any gate fails, do not comment.

Produce a recovery handoff or report the intended comment as a recommendation only.

## 20. Issue edit/update gate

Before editing an existing issue, verify:

* identity is still valid
* active profile is still valid
* runtime context is still safe
* exact edit capability is still valid
* target issue number is correct
* update is explicitly requested or required by canonical workflow
* update does not erase useful existing content
* no mode switch has occurred

If any gate fails, do not edit.

Prefer commenting over editing unless the user explicitly requested an edit or the canonical workflow requires issue body updates.

## 21. Final report must be precise

Include:

* canonical workflow source/version/hash, if available
* authenticated identity/profile
* repo/project
* runtime context summary
* exact capability proof summary
* requested issue-creation task
* duplicate search terms used
* duplicate search result
* pagination/final-page proof for issue search, if applicable
* issues created, with issue numbers and URLs
* existing issues commented, with issue numbers and URLs
* existing issues edited, with issue numbers and URLs
* issues skipped as duplicates, with issue numbers and titles
* labels/assignees/milestones applied, if any
* blockers, if stopped
* confirmation that no PR review, approval, request-changes, merge, branch, checkout, commit, push, or repo-file mutation was performed

If the report and actual tool/command log disagree, fix the report before final output.

## 22. Final report must distinguish mutation types

Do not use the legacy field `Workspace mutations`.

Use only precise categories:

* File edits by issue creator:
* Worktree/index mutations:
* Git ref mutations:
* MCP/Gitea mutations:
* Issue mutations:
* Label/assignment/milestone mutations:
* External-state mutations:
* Read-only diagnostics:

Use precise wording:

* `File edits by issue creator: none`
* `Worktree/index mutations: none`
* `Git ref mutations: none`
* `Issue mutations: ...`

If no repo files were edited, say:

`File edits by issue creator: none`

If no branches/worktrees were touched, say:

`Worktree/index mutations: none`

If no git refs were updated, say:

`Git ref mutations: none`

Do not hide issue mutations inside vague `MCP/Gitea mutations`.

## 23. Local artifact and report consistency rule

Do not create local walkthrough, notes, markdown, JSON, or report artifacts during issue-creation runs unless the canonical workflow or operator explicitly requires it.

If any file is edited, created, generated, or written, report it under `File edits by issue creator`.

For each file write, report:

* exact path
* whether it was inside the repo
* whether it was tracked or untracked
* why it was created
* whether final status was checked after the write

Do not say `File edits by issue creator: none` if any file write occurred.

Do not write files after the final clean-status check unless you rerun and report a new final clean-status check.

Default behavior: do not create local artifacts during issue creation.

## 24. Forbidden final-report claims unless proven

Do not claim:

* `duplicate search complete`
* `no duplicate found`
* `issue created`
* `issue commented`
* `issue updated`
* `label applied`
* `capability proven`
* `runtime safe`
* `all gates passed`
* `no file edits`
* `no unsafe mutation`
* `no PR mutation`
* `no repo mutation`
* `pagination complete`
* `final page`
* `no next page`

unless the corresponding proof is included.

If anything blocks safe issue creation or issue update, stop immediately and produce an executable recovery handoff.

Do not improvise around the gates.

## 25. Proof wording enforcement

The following phrases are forbidden unless directly supported by current-session evidence:

* duplicate search complete
* no duplicate found
* issue created
* issue commented
* issue updated
* labels applied
* capability proven
* runtime safe
* all gates passed
* no file edits
* no unsafe mutation
* no PR mutation
* no repo mutation
* pagination complete
* final page
* no next page

If the proof comes from prior state rather than a command/tool run in the current session, label it as prior proof, not live proof.

If a tool call was rejected, confirmation-gated, dry-run-only, or no-op, report it separately from performed mutations.

## 26. Final self-check before output

Before final output, check the report for contradictions.

Verify:

* if any file was edited, `File edits by issue creator` is not `none`
* if any worktree was added/removed, `Worktree/index mutations` lists it
* if any fetch happened, `Git ref mutations` lists it
* if any issue was created, `Issue mutations` lists it
* if any issue was commented, `Issue mutations` lists it
* if any issue was edited, `Issue mutations` lists it
* if any labels/assignees/milestones were changed, the correct mutation category lists it
* if duplicate search is claimed complete, pagination/final-page proof is present or limitation is disclosed
* if no duplicate is claimed, search terms and results are present
* if issue created is claimed, issue number and URL are present
* if no PR mutation is claimed, no PR tool/action was used
* if no repo mutation is claimed, no branch/worktree/file/commit/push action occurred
* if all gates passed is claimed, every required gate has proof

If any contradiction exists, fix the final report before output.

## 27. Controller handoff schema

End every run with a controller handoff using this schema.

Do not omit fields. Use `none` or `not verified in this session` where appropriate.

Controller Handoff:

* Task:
* Repo:
* Role:
* Identity:
* Active profile:
* Runtime context:
* Requested issue task:
* Workflow source:
* Capability proof:
* Duplicate search terms:
* Duplicate search pagination proof:
* Duplicates found:
* Issues created:
* Issues commented:
* Issues edited:
* Issues skipped as duplicates:
* Labels/assignees/milestones changed:
* File edits by issue creator:
* Worktree/index mutations:
* Git ref mutations:
* MCP/Gitea mutations:
* Issue mutations:
* Label/assignment/milestone mutations:
* External-state mutations:
* Read-only diagnostics:
* Blockers:
* Current status:
* Safe next action:
* Safety statement:

## 28. Stop conditions summary

Stop immediately and produce a recovery handoff if:

* canonical workflow is required but cannot be loaded
* identity/profile/capability cannot be proven
* runtime context is blocked
* infra stop appears
* MCP reconnect fails
* capability state is stale
* duplicate search cannot be performed and best-effort creation is not allowed
* issue search pagination cannot be proven and best-effort creation is not allowed
* duplicate fully covers the requested issue
* requested issue body is unsafe or not actionable
* target repo cannot be proven
* create_issue capability is missing
* issue_comment capability is missing for a required comment
* issue edit capability is missing for a required edit
* mode switch would be required
* any report contradiction cannot be resolved

Blocked handoffs must not include direct issue-create or issue-comment replay commands.

Blocked handoffs must say to rerun the full workflow after the blocker clears.

Do not improvise around the gates.