Files

T

sysadmin 6200e6bbec docs: split LLM project workflow into task-specific modes (Closes #333 )

Consolidate all four canonical workflow files and router SKILL.md:
- review-merge-pr.md (from #334 canonical prompt)
- reconcile-landed-pr.md (reconciliation gates + handoff schema)
- create-issue.md (canonical issue-creation prompt)
- work-issue.md (canonical author/coder prompt)

SKILL.md is now a short router with mode isolation and universal rules.
Adds final-report schemas for all modes and 13 doc-contract tests.

Supersedes partial split work in PR #335; full #333 acceptance in one PR.

2026-07-07 03:44:21 -04:00

21 KiB

Raw Blame History

task_mode, canonical, final_report_schema

task_mode	canonical	final_report_schema
create-issue	true	../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.

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.